API pública

Implementaciones API

Active implementaciones, consulte registros de implementación y transmita eventos de canalización.

La superficie de implementaciones cubre compilaciones de vista previa, publicaciones de producción y flujos de eventos de canalización. Las rutas no tienen prefijo y tienen su raíz en https://api.showly.ai (no hay prefijo de versión).

Crear una implementación

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "preview",
  "commitSha": "abc123...",
  "branch": "main"
}

Esta es la única ruta que crea una implementación (siteId está en la ruta; no hay POST /deployments). Requiere un encabezado Idempotency-Key: una clave faltante devuelve 428 y una clave reproducida que entra en conflicto devuelve 409. Devuelve 202 + un registro de implementación en el estado queued. La compilación se ejecuta de forma asincrónica; suscribirse a eventos o sondear el registro de implementación.

{
  "ok": true,
  "data": {
    "id": "8c9d3e2a-4f1b-4c6d-9a2e-1f0b3c4d5e6f",
    "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target": "preview",
    "status": "queued",
    "createdAt": "2026-05-14T15:00:00Z"
  }
}

El campo de entorno en un registro de implementación se denomina target y es uno de preview, staging o production.

Publicar en producción

Las publicaciones de producción utilizan el mismo punto final con environment: "production" y un sourceDeploymentId que nombra la vista previa ready ya creada que se promociona:

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "production",
  "sourceDeploymentId": "dep_01HZX..."
}

La publicación de producción no requiere inscripción en OTP o MFA. Todavía requiere un acción de publicación explícita y, cuando el espacio de trabajo tiene approvalWorkflows habilitado, una aprobación en segunda persona. Los agentes usan request_publish cuando eso la política está habilitada o la confirmación de dos pasos publish_site en caso contrario.

Obtener una implementación

GET /deployments/{deploymentId}

Un estado de implementación es exactamente uno de cinco valores:

queued → building → ready
                  ↘ failed
                  ↘ canceled

ready es el estado de éxito del terminal para implementaciones de versión preliminar y de producción; failed y canceled son los estados de falla terminal. No hay estado built o live. Una implementación de vista previa ready lleva su dirección en el campo url; un despliegue de producción ready sirve a la ruta de producción del sitio.

Progreso de la construcción de la transmisión

El progreso de la construcción en vivo se transmite a través de SSE desde la superficie de vistas previas:

GET /previews/{deploymentId}/stream
Accept: text/event-stream

La secuencia emite transiciones de estado y se cierra cuando la implementación alcanza un estado terminal. Para lecturas post hoc, dos puntos finales simples cubren la mayoría de las necesidades:

GET /deployments/{deploymentId}/log?lineCount=200: la cola del registro de compilación capturado.
GET /deployments/{deploymentId}/diagnostics: un paquete de fallas estructurado (etapa, código de error, cola de registro, hipótesis clasificadas) diseñado para la autodepuración del agente.

Aprobar/rechazar una solicitud de publicación de producción

POST /approvals/{requestId}/decision
Content-Type: application/json

{
  "decision": "approve" | "reject",
  "notes": "looks good"
}

Requiere una membresía de usuario activa con un rol de aprobación permitido. El actor originador tiene prohibido aprobar su propia solicitud (separación de funciones).

Revertir

No hay punto final de reversión REST. Volver a una implementación anterior es solo una operación de interfaz de usuario web. Para volver a publicar una vista previa ready anterior, llame a POST /sites/{siteId}/deploy con environment: "production" y la identificación de esa implementación como sourceDeploymentId; Se siguen aplicando la aprobación, la cuota y los controles de seguridad normales, pero no se requiere la inscripción en OTP.

Listar implementaciones

GET /deployments

Devuelve la lista de implementación completa para su espacio de trabajo como una matriz simple; todavía no hay parámetros de filtro ni paginación. Para el historial de un solo sitio, use GET /sites/{siteId}/deployments.

Errores específicos de implementaciones

Código	Estado	Significado
`idempotency_key_required`	428	`POST /sites/{siteId}/deploy` fue llamado sin un encabezado `Idempotency-Key`.
`idempotency_key_conflict`	409	El `Idempotency-Key` suministrado ya se utilizó con una solicitud diferente.
`deployment_not_found`	404	El token no puede ver esta implementación.
`approval_required`	428	La publicación de producción necesita una aprobación antes de poder promocionarse.
`source_deployment_required`	428	La publicación de producción debe nombrar la vista previa `ready` a través de `sourceDeploymentId`.
`self_approval_forbidden`	403	El aprobador es el actor originador (separación de funciones).
`source_deployment_not_found`	404	El `sourceDeploymentId` no existe o no es visible para tu token.
`source_deployment_not_ready`	409	La implementación de origen nombrada no se encuentra en un estado publicable (`ready`).

Al agotar la cuota de implementación mensual se devuelve 402 con un error de cuota: actualice el plan o espere el reinicio mensual.

Patrones

Espere a que finalice una implementación (CI):

DEP=$(curl ... | jq -r .data.id)
while :; do
  S=$(curl -sS .../deployments/$DEP | jq -r .data.status)
  [ "$S" = "ready" ] && break
  { [ "$S" = "failed" ] || [ "$S" = "canceled" ]; } && exit 1
  sleep 10
done

Lea el registro de compilación:

curl -sS ".../deployments/$DEP/log?lineCount=500" \
  | jq -r '.data.lines[]' | tee build.log

Para la mayoría de las automatizaciones, la MCP create_preview herramienta es más simple: la REST API existe para los casos MCP no encaja.