API pública

Público API descripción general

Cuándo utilizar la superficie REST API directamente en lugar de la superficie MCP.

El REST API público de Showly existe para los casos en que la superficie MCP no encaja: scripts de CI, paneles personalizados, integraciones de terceros que no son agentes.

Si está escribiendo código de agente, use MCP en su lugar. La superficie MCP obtiene auditoría de primera clase, tokens con alcance y entradas con esquemas de herramientas. El REST API expone las mismas acciones pero con una semántica más flexible diseñada para la automatización escrita por humanos.

URL base

https://api.showly.ai

Todas las solicitudes requieren TLS. Las solicitudes HTTP sin cifrar se rechazan.

Versionado

Hoy en día no hay prefijo /v1/ ni encabezado Api-Version; el API es de vía única. Tratamos cualquier cambio importante como un evento notable: aparece en el registro de cambios público, con la fecha, la ruta afectada y una nota de migración. Consulte esa página si su integración es crítica. Los cambios adicionales (nuevos campos opcionales, nuevos puntos finales) se envían sin ceremonias.

Autenticación

Cada solicitud necesita un encabezado Authorization: Bearer <token>. Las credenciales que usarás:

  • Tokens de acceso personal (PAT): prefijo sk_live_ / sk_test_. Una PAT tiene como alcance el espacio de trabajo único en el que se creó y tiene los alcances que usted le otorga en el momento de su creación. Conveniente para secuencias de comandos ad-hoc y CI.
  • MCP tokens: prefijo mcp_live_ / mcp_test_, emitido desde Configuración del espacio de trabajo → MCP clientes o acuñado por el flujo del dispositivo. Abarcado a un único espacio de trabajo y utilizado por la superficie MCP; también autentican REST llamadas.

Para instalaciones de agentes que no pueden pegar un token estático, Showly admite un flujo de autorización de dispositivo RFC 8628 (POST /oauth/device, luego sondea POST /oauth/token) que genera un token MCP vinculado al usuario autorizado. Consulte Autenticación para conocer el flujo completo y la rotación de tokens.

Sobre de respuesta

Cada respuesta JSON utiliza el mismo sobre. Respuestas exitosas:

{
  "ok": true,
  "data": { ... }
}

Errores:

{
  "ok": false,
  "error": { "code": "string", "message": "string" }
}

error.code es el contrato estable: bifurca en él, no en error.message. Los códigos son identificadores en forma de kebab o serpiente (rate_limited, idempotency_key_conflict, not_found). Los mensajes están destinados a lectores humanos y pueden cambiar entre versiones.

Límites de tarifas

Los límites de velocidad se seleccionan de la lista activa del espacio de trabajo autenticado. configuración. MCP los tokens utilizan el límite conservador de 60 solicitudes/minuto independientemente de la facturación del espacio de trabajo. Las rutas calientes pueden tener límites por ruta más estrictos.

Cuando la velocidad es limitada, el servidor devuelve HTTP 429 con error.code: "rate_limited" y un encabezado Retry-After que lleva el retroceso en segundos. Trate Retry-After como la espera canónica; no lo vuelvas a intentar antes.

Idempotencia

Crear una implementación - POST /sites/:siteId/deploy - requiere un encabezado Idempotency-Key. Sin él, el servidor regresa 428. La clave es tu elección; Recomendamos un UUID por intento lógico. (Las publicaciones de producción siguen la misma ruta con environment: "production" y sourceDeploymentId, por lo que tienen el mismo requisito). Ninguna otra ruta requiere el encabezado.

Las repeticiones de la misma clave devuelven la respuesta almacenada en caché de la primera llamada. Si el cuerpo de la solicitud cambia bajo la misma clave, el servidor devuelve 409 con idempotency_key_conflict.

Las solicitudes GET de solo lectura son naturalmente idempotentes e ignoran el encabezado.

Paginación

Los puntos finales de lista (GET /sites, GET /deployments) actualmente devuelven el conjunto de resultados completo para su espacio de trabajo como una matriz simple; todavía no hay ningún cursor ni parámetro limit. Cuando se envíe la paginación, será aditiva (cursores opacos), anunciada en el registro de cambios.

Superficies

  • Autenticación: emisión y rotación de tokens.
  • Sitios: enumerar, crear e inspeccionar sitios.
  • Implementaciones: cree implementaciones, consulte el estado y el historial, transmita eventos de canalización.