Skip to content

API Reference ​

Contentrain Studio exposes a REST API under /api/. All endpoints use JSON for request and response bodies. The API is organized around Studio's resource hierarchy: workspaces, projects, and their sub-resources.

API Surfaces & Stability ​

Studio's HTTP surface splits into two distinct contracts. Read this before integrating against any endpoint.

Public, versioned APIs live under /api/{forms,comments,media,cdn,conversation,mcp}/v1/.... They never use session cookies: each authenticates inside the route with an API key or Bearer token, or -- for the embeddable forms and comments surfaces -- is public and protected by captcha and rate limits. They are explicitly versioned with a /v1/ segment and form the stable external contract intended for third-party integrations. Breaking changes ship under a new version segment.

SurfaceBase PathAuth
Forms/api/forms/v1/Public (Turnstile captcha + rate limit)
Comments/api/comments/v1/Public (Turnstile captcha + rate limit)
Media/api/media/v1/API key
CDN/api/cdn/v1/API key
Conversation API/api/conversation/v1/crn_conv_ Bearer key (EE-only)
MCP Cloud/api/mcp/v1/crn_mcp_ Bearer key

Internal SPA routes are everything else -- /api/workspaces/..., /api/auth/..., and the projects, content, branches, chat, and webhooks management endpoints. These power the Studio dashboard itself. They use cookie/session authentication, are not a versioned public contract, and are subject to change without notice. The pages below document them for self-hosters and contributors, not as a stability guarantee.

WARNING

Build external integrations against the versioned /v1/ surfaces only. The internal SPA routes may change shape between releases.

Base URL ​

{NUXT_PUBLIC_SITE_URL}/api

For local development: http://localhost:3000/api

Authentication ​

Most endpoints require a valid session. Authentication is cookie-based using an AES-256 encrypted httpOnly cookie (contentrain-session) -- there are no Bearer tokens for the Studio UI API. The versioned public APIs above authenticate on their own and ignore the session.

Session Lifecycle ​

  1. Client calls POST /api/auth/login to get an OAuth redirect URL
  2. User completes OAuth flow (GitHub or Google)
  3. The session is established:
    • Supabase pair: the callback page calls POST /api/auth/verify with the authorization code and state, and the server sets the encrypted session cookie.
    • Managed pair: the browser is sent to GET /api/auth/oauth/:provider, which finishes the exchange itself and sets the cookie before redirecting into the app. Magic links land on GET /api/auth/magic/verify.
  4. All subsequent requests include the cookie automatically
  5. The auth middleware auto-refreshes tokens 5 minutes before expiry

See Authentication for each route.

Public Endpoints ​

The session check skips these paths (several authenticate themselves inside the route instead):

EndpointPurpose
POST /api/auth/loginGet OAuth redirect URL
POST /api/auth/verifyExchange code/token for session
POST /api/auth/refreshExchange a refresh token (CLI)
POST /api/auth/magic-linkSend magic link email
GET /api/auth/magic/verifyMagic-link landing (managed pair)
GET /api/auth/oauth/:providerOAuth sign-in legs (managed pair)
POST /api/auth/review-loginDirectory-review password login (managed pair, opt-in)
GET /api/healthHealth check
POST /api/webhooks/githubGitHub webhook receiver
POST /api/billing/webhook/:providerBilling webhook receiver (per provider)
GET /api/cdn/v1/:projectId/*CDN content delivery (API key auth; media binaries also support a keyless public-media mode gated by cdn_public_media)
/api/media/v1/:projectId/*Media management API (Bearer CDN key with media:* scope)
GET /api/forms/v1/:projectId/:modelId/configForm schema (public)
POST /api/forms/v1/:projectId/:modelId/submitForm submission (public)
GET/POST /api/comments/v1/:projectId/:modelId/:entryIdRead and post comments (public)
POST /api/conversation/v1/:projectId/messageConversation API (Bearer conversation key)
GET /api/conversation/v1/:projectId/historyConversation history (Bearer conversation key)
/api/mcp/*MCP Cloud (crn_mcp_ Bearer key) and the OAuth-authenticated remote endpoint

Forms and comments also answer CORS preflight (OPTIONS) for any origin so they can be called from the embedding site.

Request Format ​

Headers ​

http
Content-Type: application/json
Cookie: <session-cookie>

URL Parameters ​

Path parameters use Nuxt file-based routing convention:

/api/workspaces/:workspaceId/projects/:projectId/content/:modelId

Query Parameters ​

Most list endpoints (workspaces, projects, members) return the full list as a plain array or object with no pagination. A few endpoints accept their own paging parameters, documented on their pages:

EndpointParameters
Project activitypage (default 1), limit (default 20, max 100)
Comments (admin list)page (default 1), limit (default 50, max 100)
Form submissionspage (default 1), limit (default 50, max 100)
Project receiptslimit only (default 50, max 200)

Response Format ​

Success Response ​

json
{
  "workspace": {
    "id": "uuid",
    "name": "My Workspace",
    "slug": "my-workspace"
  }
}

List endpoints return arrays:

json
[
  { "id": "uuid", "name": "Project 1" },
  { "id": "uuid", "name": "Project 2" }
]

Error Response ​

json
{
  "statusCode": 403,
  "message": "You do not have permission to perform this action"
}

Error Codes ​

Status CodeMeaning
400Bad Request -- missing or invalid parameters
401Unauthorized -- no valid session
402Payment Required -- billing locked (trial expired, subscription canceled)
403Forbidden -- insufficient permissions or feature not available on plan
404Not Found -- resource does not exist
409Conflict -- duplicate resource (e.g., duplicate project for same repo)
422Unprocessable -- a submitted configuration failed validation
429Too Many Requests -- rate limit exceeded
500Internal Server Error
502Bad Gateway -- an upstream call (GitHub, content branch) failed

Rate Limiting ​

Rate limits are applied per-IP for public endpoints and per-session for authenticated endpoints:

Endpoint GroupLimitWindow
Auth (login/verify/refresh)10 requests1 minute
Magic link, review login5 requests1 minute
Form submission10 requests per model1 minute
Form config30 requests1 minute
General APIVariesPer-endpoint

INFO

In production with Redis, rate limiting is distributed across instances. Without Redis, rate limiting is in-memory and per-instance only.

Server Middleware ​

API requests pass through these middleware layers in order:

  1. Public CORS middleware (00.public-cors.ts) -- adds CORS headers and answers OPTIONS preflight for /api/forms/ and /api/comments/ only
  2. Auth middleware (01.auth.ts) -- validates session, auto-refreshes tokens (skips the public paths above)
  3. Accept invite middleware (02.accept-invite.ts) -- processes pending workspace invitations
  4. Path id guard (02b.path-ids.ts) -- answers 404 when a workspace or project id in the path is not a UUID, so malformed ids never reach the database
  5. Billing middleware (03.billing.ts) -- resolves workspace billing state on /api/workspaces/:workspaceId/... routes and returns 402 for locked workspaces; /billing/ routes stay reachable so the owner can pay
  6. Audit middleware (04.audit.ts) -- on DELETE requests to registered routes, snapshots the record before it is deleted so the audit log can store it

API Sections ​

SectionBase PathDescription
Authentication/api/auth/, /api/profile/, /api/oauth/consentLogin, verify, magic link, logout, session, profile, OAuth consent, remote-MCP OAuth endpoints
Workspaces/api/workspaces/Workspace CRUD, members, AI keys, billing, GitHub installation
MCP Cloud Keys.../mcp-cloud-keys/crn_mcp_ key create, list, revoke
Connected Apps.../connected-apps/Remote-MCP OAuth grants (managed pair)
Usage.../usageMetered usage for the billing period
Overage Settings.../overage-settingsPer-category overage toggles
Projects.../projects/Project CRUD, members, configuration, activity, receipts, migrated-site setup
Content.../content/Content save, status updates, brain sync
Chat.../chatSSE chat endpoint with agent tools
Branches.../branches/Branch list, diff, merge, reject
Media.../media/Media upload, list, update, delete
Forms/api/forms/v1/Public form config and submission
CDN.../cdn/CDN settings, builds, keys, delivery
Webhooks.../webhooks/Webhook CRUD, test, deliveries
Deploy.../deploy/Deploy-hook settings, trigger, approval
Comments/api/comments/v1/Public comment read and submit; admin moderation under .../comments/
Conversation API/api/conversation/v1/Public conversation endpoints

Released under the AGPL-3.0 License. Privacy