Content API
Internal Application API
These are internal SPA routes (cookie/session authenticated, used by the Studio app), not a versioned public contract — they may change between releases. To read published content externally, use the CDN Delivery API.
Content operations in Studio are performed through the chat agent (SSE endpoint) or through direct API calls for programmatic use. The direct API provides content save, status management, and dictionary key removal and renaming.
All content endpoints are project-scoped:
/api/workspaces/:workspaceId/projects/:projectId/content/...Save Content
Save content entries to a model. Creates a cr/* branch, commits the changes, and optionally auto-merges based on workflow configuration.
POST /api/workspaces/:workspaceId/projects/:projectId/content/:modelIdRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
locale | string | No | Locale code (default: en) |
data | object | Yes | Content data (format depends on model kind) |
publish_at | string | null | No | Scheduled publish time (ISO string). null clears it; omit to leave it unchanged |
expire_at | string | null | No | Scheduled expiry time (ISO string). null clears it; omit to leave it unchanged |
publish_at and expire_at are stored as entry metadata beside data; they never change an entry's status.
Data Format by Kind
Collection:
{
"data": {
"a1b2c3d4e5f6": {
"title": "My Blog Post",
"excerpt": "A brief summary"
}
}
}Singleton:
{
"data": {
"headline": "Welcome to Studio",
"tagline": "Fresh ideas for your team"
}
}Dictionary:
{
"data": {
"auth.sign_in_title": "Sign in to your account",
"auth.sign_in_button": "Sign In"
}
}Response
The response is the engine's WriteResult ({ branch, commit, diff, validation }) spread with the merge outcome (merged, workflow, pullRequestUrl). There is no top-level commitSha, filesChanged, valid, or errors — the commit SHA lives under commit.sha, the changed files under diff, and validity under validation:
{
"branch": "cr/content/blog-post/en/1774800862-27c1",
"commit": {
"sha": "abc123def456",
"message": "contentrain: save blog-post [en]",
"author": { "name": "Contentrain Studio", "email": "ai@contentrain.io" },
"timestamp": "2026-01-15T12:00:00.000Z"
},
"diff": [
{ "path": ".contentrain/content/blog-post/en.json", "status": "modified" }
],
"validation": { "valid": true, "errors": [] },
"merged": true,
"workflow": "auto-merge",
"pullRequestUrl": null
}When validation fails, the endpoint returns the same WriteResult shape early with validation.valid: false and populated validation.errors (and an empty branch). pullRequestUrl is populated only when the merge opens a pull request instead of merging directly; otherwise it is null.
When the save is not merged (merged: false), the branch is left open for review and the response also carries an approval object explaining why: { risk, reasons, outstanding }, where outstanding lists the approvals still missing (gate, mode, min_approvals, remaining). The merge is decided by the same approval gate the chat agent uses, so a save made in the editor and the same save made through chat are held or merged alike.
Auth
Requires editor, admin, or owner role. Errors:
| Status | Condition |
|---|---|
400 | data is missing |
403 | The caller cannot save content in this project, or the model is outside the models their access is limited to |
Update Entry Status
Change the publish status of content entries.
PATCH /api/workspaces/:workspaceId/projects/:projectId/content/:modelId/statusRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
locale | string | No | Locale code (default: en) |
entryIds | string[] | Yes | Entry IDs to update |
status | 'draft' | 'published' | 'archived' | Yes | Target status |
Response
{
"merged": true,
"workflow": "auto-merge",
"status": "published",
"entryIds": ["a1b2c3d4e5f6"],
"statusChanges": [ ... ]
}status and entryIds echo the request; merged reports whether the status-change branch was merged. statusChanges lists each entry's transition. Two other shapes:
- When every named entry already has the requested status, nothing is committed and the response is
{ "merged": false, "unchanged": true, "status", "entryIds", "statusChanges" }. - When the approval gate holds the change, the response has
merged: false, the openbranch, and the sameapprovalexplanation the save route returns.
Auth
Publishing (status: "published") requires workspace owner or admin (403). Moving entries to draft or archived requires the same access as saving content. Other errors: 400 for a missing entryIds/status or an invalid status, 403 when the model is outside the caller's allowed models.
Remove or Rename Dictionary Keys
Remove keys from, or rename a key in, a dictionary model (400 for any other model kind).
PATCH /api/workspaces/:workspaceId/projects/:projectId/content/:modelId/keysSend exactly one of the two operations (400 otherwise):
| Field | Type | Description |
|---|---|---|
remove | string[] | Keys to delete. They are removed from every locale that holds them |
locales | string[] | With remove only: limit the removal to these locales |
rename | { from: string, to: string } | Rename a key in one commit across every locale that holds from |
A rename is refused (validation error in the response) when to already exists in any locale, when from is not found, or when to equals from.
Response
Same shape as Save Content: the WriteResult plus merged, workflow, pullRequestUrl, and the approval explanation when the change is held for review. If validation fails, the WriteResult is returned early with validation.valid: false.
Auth
Both operations are treated as deletes: they require the delete_content permission (editor, admin, or owner; 403 otherwise), plus access to the model. A site that reads the old key breaks either way, so a rename goes through the same approval gate as a delete.
Brain Sync
Returns the project brain cache: the full content snapshot used by the chat agent and context panel. The route reads (or builds) the cache; it does not force a refresh.
GET /api/workspaces/:workspaceId/projects/:projectId/brain/syncAny project member. Optional query: ?treeSha=<hash>. If it equals the current tree SHA, only a delta marker is returned (see below).
Response
{
"treeSha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
"delta": false,
"config": {
"stack": "nuxt",
"locales": { "default": "en", "supported": ["en", "tr"] },
"domains": ["marketing", "blog"],
"workflow": "auto-merge"
},
"models": {
"blog-post": {
"id": "blog-post",
"name": "Blog Post",
"kind": "collection",
"domain": "blog",
"i18n": true,
"fields": { ... }
}
},
"content": {
"blog-post:en": {
"kind": "collection",
"data": {
"a1b2c3d4e5f6": { "title": "My Post" }
},
"meta": {
"a1b2c3d4e5f6": {
"status": "published",
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-15T00:00:00Z"
}
}
}
},
"vocabulary": { ... },
"contentContext": { ... },
"contentSummary": { ... },
"schemaValidation": {
"healthScore": 95,
"modelCount": 5,
"validModels": 5,
"warnings": []
},
"access": {
"availableTools": ["list_models", "get_content", "save_content"],
"specificModels": false,
"allowedModels": []
}
}models is an object keyed by model ID. Each content entry is keyed modelId:locale and holds { data, meta, kind }; meta is null for a model without metadata. access describes what the caller may do in this project (the content panel uses it to hide write controls; the save routes remain the authority).
Delta response
When treeSha matches the current tree, nothing is resent:
{
"treeSha": "9fceb02d0ae598e95dc970b74767f19372d61af8",
"delta": true,
"config": null,
"models": null,
"content": null,
"vocabulary": null,
"contentContext": null,
"contentSummary": null,
"access": { ... }
}Brain Cache
The brain cache is an in-memory representation of the project content, built from Git on first access and invalidated after any write operation. It is used by the chat agent for fast content reads.
Content Engine
Behind the scenes, all content operations go through the Content Engine (server/utils/content-engine/). The engine orchestrates:
- Validation -- schema-based content validation using model field definitions
- Serialization -- canonical JSON output (sorted keys, 2-space indent, trailing newline)
- Branching -- creates a
cr/*feature branch from thecontentrainSSOT branch - Commit -- commits file changes via the GitProvider
- Auto-merge -- merges the branch back if workflow and permissions allow
See Content Engine for full internals.
Related Pages
- Chat API -- content operations via AI agent
- Branches API -- managing content branches
- Field Types -- supported field type reference
- Content Engine -- write path internals