Skip to content

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/:modelId

Request Body ​

FieldTypeRequiredDescription
localestringNoLocale code (default: en)
dataobjectYesContent data (format depends on model kind)
publish_atstring | nullNoScheduled publish time (ISO string). null clears it; omit to leave it unchanged
expire_atstring | nullNoScheduled 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:

json
{
  "data": {
    "a1b2c3d4e5f6": {
      "title": "My Blog Post",
      "excerpt": "A brief summary"
    }
  }
}

Singleton:

json
{
  "data": {
    "headline": "Welcome to Studio",
    "tagline": "Fresh ideas for your team"
  }
}

Dictionary:

json
{
  "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:

json
{
  "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:

StatusCondition
400data is missing
403The 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/status

Request Body ​

FieldTypeRequiredDescription
localestringNoLocale code (default: en)
entryIdsstring[]YesEntry IDs to update
status'draft' | 'published' | 'archived'YesTarget status

Response ​

json
{
  "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 open branch, and the same approval explanation 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/keys

Send exactly one of the two operations (400 otherwise):

FieldTypeDescription
removestring[]Keys to delete. They are removed from every locale that holds them
localesstring[]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/sync

Any project member. Optional query: ?treeSha=<hash>. If it equals the current tree SHA, only a delta marker is returned (see below).

Response ​

json
{
  "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:

json
{
  "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:

  1. Validation -- schema-based content validation using model field definitions
  2. Serialization -- canonical JSON output (sorted keys, 2-space indent, trailing newline)
  3. Branching -- creates a cr/* feature branch from the contentrain SSOT branch
  4. Commit -- commits file changes via the GitProvider
  5. Auto-merge -- merges the branch back if workflow and permissions allow

See Content Engine for full internals.

Released under the AGPL-3.0 License. Privacy