HTTP API reference

All endpoints sit under /api/. Public visitor traffic does NOT go through this server — visitors hit the static artifacts directly via S3+CloudFront, the manifest-pointer L@E resolver, or a customer-owned GitHub repo (depending on STATICOWL_DEPLOY_TARGET). The /api/* surface is for the admin UI, programmatic clients, MCP servers, and SDK consumers.

Authentication

The CMS uses Cognito ID tokens in an Authorization: Bearer … header. The browser admin (/admin/) uses amazon-cognito-identity-js to obtain and refresh tokens. Programmatic clients obtain a Cognito token via SRP flow or use a CMS-minted API key (prefix gcms_…).

Most endpoints additionally require an X-Site-Id header identifying which site the request applies to. /api/auth/*, /api/health, /api/access/*, /api/sites/* (top-level) and /api/leads are the exceptions.

Auth order (request lifecycle)

request → cognitoAuthMiddleware    → req.auth.{userId, email, name}
        → platformContext          → req.platformUser, req.platformRole
        → requireSiteContext       → req.services.{graph, content, ...}
        → route handler            → service call → engine

See architecture.md for the full picture.

Conventions

• Requests and responses are JSON unless otherwise noted.
• Dates are ISO 8601.
• Errors return { "error": "…" } with a non-2xx status.
• List endpoints accept ?q= (search), some accept ?status=, ?page=, ?limit=.
• Pagination: list responses are bare arrays for now; pagination cursors will be added per-route as scale demands.

Status codes

Health

GET /api/health

No auth. Returns { status: "ok", lastBuildAt, lastBuildId }.

Access / sites

GET /api/access/my-sites

Returns the sites the current user has access to — used by the admin UI to bootstrap the site picker. No X-Site-Id needed.

[
  { "siteId": "...", "siteName": "Kindatechnical", "graphName": "kindatechnical", "role": "admin" }
]

GET /api/access/site-users (admin only, site-scoped)

Lists users with access to the current site.

POST /api/access/grant (admin only)

Grants a user access to the current site. Body: { userId, role } (role ∈ admin | editor | publisher).

GET /api/sites/

Owner / admin: lists every site on the platform. Other roles: lists only sites the user has access to.

POST /api/sites/

Creates a new site. Grants the creator admin access automatically. Body:

{
  "name": "My Site",
  "publicUrl": "https://example.com",
  "slug": "my-site",
  "starterKit": "developer | author | designer | none",
  "description": "...",
  "mantra": "...",
  "theme": { "primary": "#5A7D4D", "accent": "#FBBF24" }
}

If starterKit is omitted, the user's persona is used. Starter kits seed the new site's graph with default content types + templates.

GET /api/sites/:id (admin / owner / member)

Site detail.

DELETE /api/sites/:id (owner only)

Soft-deletes the site. Engine retains data for the configured retention period.

Auth (site-member management)

These are NOT login/registration — Cognito handles that at the gateway. These manage site members for the current site.

GET /api/auth/users

Lists members of the current site. Requires X-Site-Id.

PUT /api/auth/users/:id/role

Change a member's site role. Body: { role: "admin" | "editor" | "publisher" | "viewer" }.

DELETE /api/auth/users/:id

Revokes the user's access to the current site.

GET /api/auth/api-keys

Lists CMS-minted API keys for the current site (prefix gcms_…). Returns key metadata, not the secret.

POST /api/auth/api-keys

Mints a new key. Body: { name, role }. Response includes the secret once — store it.

DELETE /api/auth/api-keys/:id

Revokes a key.

Content

Content-type names are used as path segments (e.g., article, page).

Content body persists the Editor.js output format: { time, blocks: [{ type, data }], version }.

Content types

Templates, scripts, queries, routes, views, block-types, workflows, locales, transforms, widgets

Each of these is a CRUD-style schema/asset endpoint:

All follow the same shape: GET / lists, GET /:name gets, POST / creates, PUT|PATCH /:name updates. See Lifecycle hooks for transforms specifically.

Releases / Deployments

The /api/releases namespace is where the deploy story lives. Releases are immutable bundles; Deployments point a Release at an environment with a validFrom. See features.md → Releases for concepts.

Environments

Releases

Deployments

Drip publishing

Schedule N approved Releases across a time window. Each Release gets its own Deployment with a staggered validFrom; the scheduler fires each Deployment at its time. Three patterns: even, random, jittered. Preview-then-approve.

See features.md → Drip publishing for examples.

Replay

Build

AI

The /api/ai namespace exposes the AI assistant capabilities. See ai.md for the full feature breakdown.

Common shape:

• POST /api/ai/chat — chat completion proxied through Anthropic / OpenAI
• POST /api/ai/draft — voice-aware content draft
• POST /api/ai/derive — multi-asset derive (one upload → blog + tweets + LinkedIn + email + alt text)
• POST /api/ai/import — document → structured pages
• POST /api/ai/visual-edit — edit-this-paragraph
• POST /api/ai/bulk-rewrite — site-wide diff-preview rewrite
• POST /api/ai/site-health — full-site audit + auto-fix proposals
• POST /api/ai/voice-profile — train / preview voice profile

Media

GET /api/media/stock?provider=pexels|unsplash|pixabay&q=&orientation=landscape

Proxies to the named stock search provider. Returns a normalized { items: [{ id, url, thumb, photographer, source, width, height }] }.

GET /api/media

List uploaded assets for the current site, ordered by upload time (newest first). Query params: ?q=filename-substring, ?countOnly=1 (returns { total } only).

POST /api/media/upload

Multipart form with field file. Accepts images, videos, PDFs. 25 MB max. Returns:

{
  "ok": true, "id": "asset:...", "url": "/media/assets/<sha>.png",
  "sha256": "...", "filename": "...", "mimetype": "image/png",
  "bytes": 12345, "width": 1024, "height": 768,
  "uploadedBy": "user:...", "uploadedAt": "..."
}

Storage: local filesystem (MEDIA_DIR, default /opt/graphiquity/data/cms-media). File's SHA is both the filename and the dedup key.

DELETE /api/media/:id

Removes the Asset node and unlinks the file.

GET /media/assets/<sha>.<ext>

Static file serving. Not under /api/; no auth on reads.

Page kits

Reusable layout fragments (hero sections, CTAs, image galleries, testimonials).

Notifications, bugs, leads, export, SDK, agent

These are smaller utility namespaces:

• /notifications — in-app notification queue per user
• /bugs — bug-report intake (used by the admin "Report a bug" affordance)
• /leads — public lead intake (no auth) + admin views (/api/leads)
• /export — bulk export of content / metadata in JSON
• /sdk — endpoints consumed by the JS SDK (snapshot fetches, etc.)
• /agent — agent / scoped-token management (in development; see Architecture: scoped agent tokens)

Sample requests

Create + deploy a Release

TOKEN=$(...)
SITE=site:my-site

# 1. Create a draft Release
curl -X POST https://app.staticowl.com/api/releases \
  -H "Authorization: Bearer $TOKEN" -H "X-Site-Id: $SITE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Spring sale","intent":"deploy","includes":[]}'
# → { "id": "release:abc", "state": "draft", ... }

# 2. Add content
curl -X POST .../api/releases/release:abc/includes \
  -d '{"kind":"content","versionableId":"article:welcome","version":3,"at":"2026-04-28T..."}'

# 3. Submit for review
curl -X POST .../api/releases/release:abc/transition -d '{"state":"pending"}'

# 4. (Reviews run...)
# 5. Approve
curl -X POST .../api/releases/release:abc/transition -d '{"state":"approved"}'

# 6. Deploy
curl -X POST .../api/releases/release:abc/deploy \
  -d '{"environmentId":"env:prod","intent":"deploy"}'
# → { "id": "deploy:xyz", "status": "pending" → "deployed", ... }

Schedule 12 posts across an 8-hour window

curl -X POST .../api/releases/drip-preview \
  -d '{
    "releaseIds": ["release:1", "release:2", ..., "release:12"],
    "windowStart": "2026-05-01T08:00:00.000Z",
    "windowEnd":   "2026-05-01T16:00:00.000Z",
    "pattern": "jittered",
    "maxJitterMs": 600000,
    "seed": 42
  }'
# → { schedule: { timestamps: [...] }, pairs: [{releaseId, validFrom}, ...] }

# Operator reviews the calendar, then commits:
curl -X POST .../api/releases/drip-schedule \
  -d '{ ... same body, plus "environmentId": "env:prod" }'

Replay the site as it was on Jan 15

curl ".../api/releases/replay?envId=env:prod&atTime=2026-01-15T15:00:00.000Z" \
  -H "Authorization: Bearer $TOKEN" -H "X-Site-Id: $SITE"
# → { deployment: {...}, release: {...}, includes: [...] }

Env vars reference

See operations.md → Environment variables for the canonical list.