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.
| Surface | Base Path | Auth |
|---|---|---|
| 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}/apiFor 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
- Client calls
POST /api/auth/loginto get an OAuth redirect URL - User completes OAuth flow (GitHub or Google)
- The session is established:
- Supabase pair: the callback page calls
POST /api/auth/verifywith the authorization code andstate, 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 onGET /api/auth/magic/verify.
- Supabase pair: the callback page calls
- All subsequent requests include the cookie automatically
- 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):
| Endpoint | Purpose |
|---|---|
POST /api/auth/login | Get OAuth redirect URL |
POST /api/auth/verify | Exchange code/token for session |
POST /api/auth/refresh | Exchange a refresh token (CLI) |
POST /api/auth/magic-link | Send magic link email |
GET /api/auth/magic/verify | Magic-link landing (managed pair) |
GET /api/auth/oauth/:provider | OAuth sign-in legs (managed pair) |
POST /api/auth/review-login | Directory-review password login (managed pair, opt-in) |
GET /api/health | Health check |
POST /api/webhooks/github | GitHub webhook receiver |
POST /api/billing/webhook/:provider | Billing 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/config | Form schema (public) |
POST /api/forms/v1/:projectId/:modelId/submit | Form submission (public) |
GET/POST /api/comments/v1/:projectId/:modelId/:entryId | Read and post comments (public) |
POST /api/conversation/v1/:projectId/message | Conversation API (Bearer conversation key) |
GET /api/conversation/v1/:projectId/history | Conversation 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
Content-Type: application/json
Cookie: <session-cookie>URL Parameters
Path parameters use Nuxt file-based routing convention:
/api/workspaces/:workspaceId/projects/:projectId/content/:modelIdQuery 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:
| Endpoint | Parameters |
|---|---|
| Project activity | page (default 1), limit (default 20, max 100) |
| Comments (admin list) | page (default 1), limit (default 50, max 100) |
| Form submissions | page (default 1), limit (default 50, max 100) |
| Project receipts | limit only (default 50, max 200) |
Response Format
Success Response
{
"workspace": {
"id": "uuid",
"name": "My Workspace",
"slug": "my-workspace"
}
}List endpoints return arrays:
[
{ "id": "uuid", "name": "Project 1" },
{ "id": "uuid", "name": "Project 2" }
]Error Response
{
"statusCode": 403,
"message": "You do not have permission to perform this action"
}Error Codes
| Status Code | Meaning |
|---|---|
400 | Bad Request -- missing or invalid parameters |
401 | Unauthorized -- no valid session |
402 | Payment Required -- billing locked (trial expired, subscription canceled) |
403 | Forbidden -- insufficient permissions or feature not available on plan |
404 | Not Found -- resource does not exist |
409 | Conflict -- duplicate resource (e.g., duplicate project for same repo) |
422 | Unprocessable -- a submitted configuration failed validation |
429 | Too Many Requests -- rate limit exceeded |
500 | Internal Server Error |
502 | Bad 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 Group | Limit | Window |
|---|---|---|
| Auth (login/verify/refresh) | 10 requests | 1 minute |
| Magic link, review login | 5 requests | 1 minute |
| Form submission | 10 requests per model | 1 minute |
| Form config | 30 requests | 1 minute |
| General API | Varies | Per-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:
- Public CORS middleware (
00.public-cors.ts) -- adds CORS headers and answersOPTIONSpreflight for/api/forms/and/api/comments/only - Auth middleware (
01.auth.ts) -- validates session, auto-refreshes tokens (skips the public paths above) - Accept invite middleware (
02.accept-invite.ts) -- processes pending workspace invitations - Path id guard (
02b.path-ids.ts) -- answers404when a workspace or project id in the path is not a UUID, so malformed ids never reach the database - Billing middleware (
03.billing.ts) -- resolves workspace billing state on/api/workspaces/:workspaceId/...routes and returns402for locked workspaces;/billing/routes stay reachable so the owner can pay - Audit middleware (
04.audit.ts) -- onDELETErequests to registered routes, snapshots the record before it is deleted so the audit log can store it
API Sections
| Section | Base Path | Description |
|---|---|---|
| Authentication | /api/auth/, /api/profile/, /api/oauth/consent | Login, 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 | .../usage | Metered usage for the billing period |
| Overage Settings | .../overage-settings | Per-category overage toggles |
| Projects | .../projects/ | Project CRUD, members, configuration, activity, receipts, migrated-site setup |
| Content | .../content/ | Content save, status updates, brain sync |
| Chat | .../chat | SSE 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 |
Related Pages
- Architecture -- how the API fits into the system
- Roles & Permissions -- who can access what
- Environment Variables -- API configuration