API de publicación

Descripción general

La publicación es un flujo de tres pasos:

publish — simulación (dry-run) que genera un manifiesto de cambios revisable y un token de confirmación de corta duración. No se escriben datos.
publish-confirm — presenta el token e inicia la canalización inmediatamente. Devuelve { publish_id, status: "running" } en segundos; no espera a que finalice el despliegue.
publish-status — consulta el estado hasta que el trabajo llegue a succeeded o failed.

Autenticación: Token OAuth Bearer o clave de API de servicio. El emisor debe tener el rol manager en el proyecto.

Paso 1 — publish (simulación)

Genera un manifiesto de cambios pendientes y devuelve un token de confirmación de un solo uso. No se escribe ni se despliega nada en este paso.

Argumentos

Campo	Requerido	Notas
`project_id`	sí	El proyecto a publicar.
`project_name`	sí	Debe coincidir exactamente con el nombre del proyecto almacenado (sin distinguir mayúsculas/minúsculas). Una discrepancia devuelve un error mostrando los valores esperados y suministrados.

Respuesta

{
  "manifest": {
    "project_name": "Acme Real Estate",
    "target_site_url": "https://tf-acme.web.app",
    "drafts": [
      { "path": "abc123", "language": "en", "slug": "guides/intro", "title": "Getting started" }
    ],
    "theme_changes": { "colors": { "primary": "#14b8a6" } },
    "translations_planned": 4
  },
  "confirmation_token": "ec1a4b…(64 hex)",
  "expires_at": "2026-05-11T01:23:45.678Z"
}

El confirmation_token es de un solo uso y caduca después de 5 minutos.

Paso 2 — publish-confirm (inicio asíncrono)

Presenta el token y encola la canalización de despliegue. Devuelve una respuesta inmediata; la cadena de promoción → traducción → despliegue se ejecuta en segundo plano.

Argumentos

Campo	Requerido	Notas
`project_id`	sí	Debe coincidir con el proyecto vinculado al token.
`confirmation_token`	sí	Devuelto por `publish`.

Respuesta

{
  "publish_id": "auto-generated-id",
  "status": "running",
  "site_url": "https://tf-acme.web.app"
}

Guarde el publish_id: lo necesitará para consultar el estado y revertir la publicación en el plazo de una hora.

Paso 3 — publish-status (consulta hasta finalizar)

Consulte el estado hasta que el trabajo llegue a succeeded o failed. El emisor necesita el rol member o superior.

Argumentos

Campo	Requerido
`project_id`	sí
`publish_id`	sí

Respuesta por estado

`status`	Campos adicionales
`queued` / `running`	Consultar de nuevo.
`succeeded`	`published_urls: [{ title, language, slug, url }]` — presentar como enlaces clicables.
`failed`	`error` — el mensaje de error.

Canalización de promoción

Validación

Cada borrador se valida antes de que ocurra cualquier escritura. Un error de validación aborta todo el lote.

Regla	Error
`metadata.title` ausente	`Missing required field 'title'`
`metadata.title` no tiene 10–60 caracteres	`Title must be 10–60 characters`
`metadata.description` ausente	`Missing required field 'description'`
`metadata.description` no tiene 50–160 caracteres	`Description must be 50–160 characters`
`metadata.slug` ausente	`Missing required field 'metadata.slug'`
`content` vacío	`Content cannot be empty`
`content` empieza con `#`	`Content contains an h1. Start content with ## instead.`

Requisito de índice

Cada idioma publicado debe tener un documento activo o en el lote con metadata.slug === "index".

Concurrencia

Solo se ejecuta un trabajo de publicación a la vez por proyecto. Una llamada concurrente a publish-confirm devuelve publish in progress.

Traducciones

Tras la promoción, se crean automáticamente copias de borrador de cada documento promocionado para todos los idiomas adicionales configurados en el proyecto. Los borradores traducidos se validan en una segunda pasada antes de la promoción; una traducción defectuosa no puede llegar a producción directamente.

Omitir si no hay cambios: si el contenido original y la configuración de traducción de una variante previamente traducida son idénticos a la última publicación, la traducción se reutiliza sin realizar una nueva llamada de IA. Esto cubre tanto cambios de contenido como actualizaciones de versión del modelo de IA; una actualización de modelo nunca se omite silenciosamente.

Reversión

revert-publish revierte la acción en el plazo de una hora utilizando el publish_id de publish-confirm.

Errores

Fase	Error	Causa
Autorización	`Insufficient permission: this tool requires 'manager' on project '…'`	El emisor tiene rol `member` o ninguno.
Autorización	`project_name does not match project …: expected 'X', got 'Y'`	Fallo en la verificación de `project_name`.
Token	`Invalid or already-used confirmation token`	Token caducado, ya usado o proyecto incorrecto.
Token	`Confirmation token has expired`	Ventana de 5 minutos agotada. Ejecute `publish` de nuevo.
Bloqueo	`publish in progress`	Ya hay otra publicación en curso. Espere y reintente.
Promoción	`Validation failed for one or more drafts`	Se violó una regla de validación. Los detalles incluyen la ruta y el campo del borrador.
Promoción	`Missing mandatory index page for locale(s): …`	Falta una página de índice en un idioma configurado.
Despliegue	`{ "success": false, "error": "…" }`	Fallo de compilación o despliegue. El campo `error` contiene el detalle.

Relacionado

Servidor MCP — publicar mediante herramientas MCP (publish, publish-confirm, publish-status)
Autenticación de API — autenticación OAuth Bearer y clave de API
Sistema de traducción — cómo se traducen automáticamente los documentos al publicar
Descripción general de la API — lista completa de endpoints