Sites API

The sites surface lets you enumerate, inspect, and create the sites in a workspace. The REST API has no version prefix: all paths below are rooted at https://api.showly.ai.

List sites

GET /sites
Authorization: Bearer <token>

Returns every site the token can see (a plain array — no pagination yet), plus a sibling entitlements object with the workspace's site caps.

{
  "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": 5,
    "currentSites": 1,
    "maxLiveSites": 5,
    "currentLiveSites": 1
  }
}

Site ids are UUIDs. The framework value is a free-form string auto-detected by the builder (for example next-export, astro, static-html).

Get a single site

GET /sites/{siteId}

Returns the site plus the current manifest and most-recent deployment summary.

Create a site

POST /sites
Content-Type: application/json

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

Returns 201 + the created site. projectId is the UUID of the project the site belongs to. slug must match ^[a-z0-9-]+$ and be unique in the workspace; if it collides you get 409 with error.code: "slug_taken". framework and repositoryUrl are optional.

Build configuration lives in a showly.json manifest committed to the repository, not in the create body. The builder auto-detects the framework and reads rootDirectory, runtime, buildCommand, output, and related fields from that file. See Site manifest for the full schema.

Deploy targets

Deploy targets are configured at the organization level, not per site. They are mounted at /deployment-targets:

A target carries a provider (gcp, aws, kubernetes, static, or cloudflare), a mode (serverless-container, k8s, or static-cdn), and a runtime (node, container, or static). Only a subset of combinations is implemented today (AWS/GCP serverless containers, AWS/static static-CDN); anything else returns 400 deployment_target_not_implemented.

Registering a deployment target in your own cloud account requires an Enterprise plan — other plans get 403 ("Deploying to your own cloud account requires an Enterprise plan"). Create/update/delete also require a user actor: a token-only bot cannot register own-cloud targets.

Curl example: end-to-end create + first deploy

# 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" }'

The create-deployment call returns 202. The Idempotency-Key header is required on POST /sites/:siteId/deploy; without it the request returns 428, and a conflicting retry returns 409. See Deployments for the rest of the deploy lifecycle.

Errors