Sitios API

La superficie de sitios le permite enumerar, inspeccionar y crear los sitios en un espacio de trabajo. El REST API no tiene prefijo de versión: todas las rutas siguientes tienen su raíz en https://api.showly.ai.

Listar sitios

GET /sites
Authorization: Bearer <token>

Devuelve todos los sitios que el token puede ver (una matriz simple, sin paginación todavía), más un objeto hermano entitlements con los límites del sitio del espacio de trabajo.

{
  "ok": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectId": "9b2f1c44-0d31-4c19-8a77-0f4bd4a1c001",
      "slug": "marketing-site",
      "name": "Marketing site",
      "framework": "next-export",
      "status": "active",
      "repositoryUrl": "https://github.com/acme/marketing",
      "productionUrl": "https://marketing-site.showly.site",
      "createdAt": "2026-03-01T10:14:22Z",
      "updatedAt": "2026-07-01T08:03:10Z"
    }
  ],
  "entitlements": {
    "maxSites": "unlimited",
    "currentSites": 3,
    "maxLiveSites": "unlimited",
    "currentLiveSites": 1
  }
}

Los identificadores de sitio son UUID. El valor framework es una cadena de formato libre detectada automáticamente por el constructor (por ejemplo next-export, astro, static-html).

Cupos de sitios

maxLiveSites es el cupo comercial de sitios publicados. Su valor es "unlimited" tanto en Free como en Pro. Un contrato personalizado o una excepción de derechos todavía puede devolver un valor finito, que se comprueba al publicar.

maxSites cubre todos los registros de sitios activos, incluidos los que solo tienen una vista previa. También es "unlimited" en todos los planes base. Un valor finito solo aparece cuando un operador aplica una excepción explícita al espacio de trabajo; pasar de Free a Pro no añade sitios. Las vistas previas del espacio de trabajo no caducan.

Obtener un solo sitio

GET /sites/{siteId}

Devuelve el sitio más el manifiesto actual y el resumen de implementación más reciente.

Crear un sitio

POST /sites
Content-Type: application/json

{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Docs",
  "slug": "docs",
  "repositoryUrl": "https://github.com/acme/docs"
}

Devuelve 201 y el sitio creado. projectId es el UUID del proyecto al que pertenece el sitio. slug debe coincidir con ^[a-z0-9-]+$ y ser único en el espacio de trabajo; si entra en conflicto, se devuelve 409 con error.code: "slug_taken". framework y repositoryUrl son opcionales.

La configuración de compilación se encuentra en un manifiesto showly.json comprometido con el repositorio, no en el cuerpo de creación. El constructor detecta automáticamente el marco y lee rootDirectory, runtime, buildCommand, output y los campos relacionados de ese archivo. Consulte Manifiesto del sitio para ver el esquema completo.

Implementar objetivos

Los destinos de implementación se configuran a nivel de organización, no por sitio. Están montados en /deployment-targets:

Un objetivo lleva un provider, mode y runtime. El punto final de capacidad es la fuente de verdad para las combinaciones habilitadas en el entorno actual; enumeración Los valores en un esquema API no prometen que se aprovisione un proveedor. Las combinaciones no admitidas regresan 400 deployment_target_not_implemented.

Registrar un destino de implementación en su propia cuenta en la nube requiere la byoCloudTargets derecho y un actor de usuario. Un bot de solo token no puede crear, actualizar o eliminar un destino de nube propia.

Ejemplo de curl: creación de un extremo a otro + primera implementación

# 1. Create the site
SITE=$(curl -sS -X POST https://api.showly.ai/sites \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Demo", "slug": "demo", "repositoryUrl": "https://github.com/acme/demo" }' \
  | jq -r '.data.id')

# 2. Inspect the site (and the auto-detected manifest)
curl -sS "https://api.showly.ai/sites/$SITE" \
  -H "authorization: bearer $SHOWLY_TOKEN"

# 3. Request a preview deployment (siteId in the path; Idempotency-Key required)
curl -sS -X POST "https://api.showly.ai/sites/$SITE/deploy" \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{ "environment": "preview" }'

La llamada de creación-implementación devuelve 202. El encabezado Idempotency-Key es obligatorio en POST /sites/:siteId/deploy; sin ella, la solicitud devuelve 428 y un reintento conflictivo devuelve 409. Consulte Implementaciones para conocer el resto del ciclo de vida de la implementación.

Archivar y restaurar

Al eliminar un sitio, se archiva: desaparece de GET /sites pero aún aparece en GET /sites/archived. Un sitio no se archiva solo por permanecer en Vista previa. La eliminación explícita permite reutilizar su slug. Si el espacio de trabajo tiene una anulación explícita y finita de maxSites, la eliminación también libera uno de esos espacios anulados.

Trae uno de vuelta con:

POST /sites/:siteId/restore

El sitio regresa vacío y listo para volver a implementarse; sus implementaciones anteriores no lo están resucitado, porque sus artefactos de construcción ya han sido recolectados como basura. La restauración consume un espacio del sitio, por lo que devuelve 402 si está en su maxSites asignación, y 404 si se desconoce el id, pertenece a otro espacio de trabajo o ya está activo.

Errores