Projects 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. For external integrations, use the Public API.
Projects represent connected Git repositories within a workspace. Each project maps to one repository and contains content models, entries, media, and conversations.
All project endpoints are scoped under a workspace:
/api/workspaces/:workspaceId/projects/...List Projects
List the projects in a workspace that the caller can access.
GET /api/workspaces/:workspaceId/projectsResponse
A plain array of project rows (not paginated).
[
{
"id": "uuid",
"repo_full_name": "org/my-website",
"default_branch": "main",
"content_root": "/",
"status": "active",
"created_at": "2026-01-01T00:00:00Z"
}
]Auth
Workspace owner and admin see every project. A plain member sees only the projects they are assigned to (an empty array when none). Non-members get 403.
Create Project
Connect a GitHub repository as a new project.
POST /api/workspaces/:workspaceId/projectsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
repoFullName | string | Yes | GitHub owner/repo full name |
defaultBranch | string | No | Default branch name (defaults to main when omitted -- it is not auto-detected) |
contentRoot | string | No | Sub-path for .contentrain/ directory (e.g., apps/web); stored as / when omitted |
detectedStack | string | No | Framework detected by Scan Repository |
hasContentrain | boolean | No | Pass false when the repository has no .contentrain/ yet; the project is then created with status setup instead of active |
There is no project name field: a project is identified by its repository.
When the workspace has a GitHub App installation, the server also prepares the contentrain content branch before creating the row.
Response
The created project row.
{
"id": "uuid",
"repo_full_name": "org/my-website",
"default_branch": "main",
"content_root": "/",
"status": "active"
}Error Codes
| Status | Condition |
|---|---|
400 | repoFullName missing |
402 | The workspace is on the free plan -- a paid plan is required to connect repositories. data is { requiresCheckout: true, workspaceId } |
409 | Repository already connected in this workspace (data.code already_connected), or a delivered migration branch has not been merged into the default branch yet (data.code migration_not_merged) |
502 | The content branch could not be prepared (data.code content_branch_failed) |
Get Project
Get project details with member information.
GET /api/workspaces/:workspaceId/projects/:projectIdResponse
The project row plus a project_members array. Returns 404 when the project is not found in the workspace.
Delete Project
Delete a project (does not delete the GitHub repository).
DELETE /api/workspaces/:workspaceId/projects/:projectIdRemoves the project's CDN and media files, updates the workspace's storage usage, and deletes the project and its child records (conversations, members, CDN builds and keys, media). Returns { "deleted": true }; 404 if the project is not in the workspace.
Auth
Requires workspace owner or admin role.
Update Project Configuration
Update the Contentrain configuration for a project (.contentrain/config.json). The change is committed to the repository and always auto-merges, regardless of the project's workflow.
PATCH /api/workspaces/:workspaceId/projects/:projectId/configRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
workflow | 'auto-merge' | 'review' | No | Content workflow mode |
locales | object | No | Locale configuration with default and supported |
domains | string[] | No | Content domains |
Only the supplied fields change; locales.default and locales.supported are merged individually.
Response
{ "config": { }, "merged": true, "pullRequestUrl": null }config is the full updated configuration. pullRequestUrl is set when the merge fell back to a pull request.
Auth
Requires workspace owner or admin role. Setting workflow to review additionally requires the workflow.review plan feature.
Error Codes
| Status | Condition |
|---|---|
403 | Not an owner/admin, or workflow: 'review' on a plan without workflow.review |
404 | .contentrain/config.json not found in the repository |
422 | The merged configuration failed validation |
Project Health
Get the schema validation result for the project, computed from the project brain cache. Branch health is a separate route -- see Branches.
GET /api/workspaces/:workspaceId/projects/:projectId/healthResponse
{
"valid": true,
"warnings": [],
"healthScore": 100,
"modelCount": 4,
"validModels": 4,
"timestamp": "2026-01-01T00:00:00.000Z"
}When the brain cache holds no validation result, the response is valid: null, healthScore: null, validModels: 0, and unavailable: true.
Auth
Any user with access to the project.
Brain Sync
Read the project brain cache (building it from Git when needed). The same route is described from the content side on the Content API page.
GET /api/workspaces/:workspaceId/projects/:projectId/brain/syncQuery Parameters
| Param | Type | Required | Description |
|---|---|---|---|
treeSha | string | No | Tree hash from a previous response. If it still matches, the server answers with an empty delta |
Response
A full response carries treeSha, delta: false, config, models, content, vocabulary, contentContext, contentSummary, schemaValidation, and access (the caller's availableTools, specificModels, and allowedModels). When treeSha matches, the response is delta: true with config, models, content, vocabulary, contentContext, and contentSummary set to null; access is still included.
Auth
Any user with access to the project.
Update Vocabulary
Update the project vocabulary (shared terminology across locales). Provided terms are merged with the existing ones; set a term to null to delete it.
PATCH /api/workspaces/:workspaceId/projects/:projectId/vocabularyRequest Body
{
"terms": {
"brand_name": {
"en": "Contentrain",
"tr": "Contentrain"
}
}
}Response
{ "vocabulary": { "version": 1, "terms": { } }, "merged": true }On a project that uses the review workflow, a vocabulary edit is held like any other write: nothing is merged, and the response is merged: false with the branch that holds the change, the workflow, and (when a rule held it) an approval block describing why. Approve or reject it from the branch review panel (see Branches).
Auth
Requires a role that can save content (editor or above); viewers and reviewers get 403.
Error Codes
| Status | Condition |
|---|---|
400 | terms missing or not an object |
403 | Caller cannot save content |
409 | The write kept conflicting with concurrent edits after 3 attempts (retry) |
502 | vocabulary.json could not be read |
Update Model Metadata
Update model-level settings: the model's form configuration, its comments configuration, and the field that titles its entries. The change is committed and auto-merged.
PATCH /api/workspaces/:workspaceId/projects/:projectId/models/:modelIdRequest Body
At least one of the following (400 otherwise):
| Field | Type | Description |
|---|---|---|
form | object | Partial form configuration (enabled, public, exposedFields, requiredOverrides, honeypot, captcha, successMessage, limits, autoApprove, notifications). Merged with the existing form config. See Forms |
comments | object | Partial comments configuration, merged with the existing one. See Comments |
titleField | string | Field that titles entries in listings. Must be a text-like field (string, text, slug, email, url, code, markdown, or richtext); a dotted path such as hero.heading reaches one level into an object field. A dictionary model only accepts key |
Captcha and auto-approve settings that the plan does not include are silently reset (captcha: null, autoApprove: false, comments requireApproval: true).
Response
{ "saved": true, "merged": true, "form": { }, "comments": { }, "titleField": "title" }form and comments are present only when they were part of the request. If the resulting model definition fails validation, the response is { "saved": false, "validation": { } } and nothing is written.
Auth
Requires workspace owner or admin role.
Error Codes
| Status | Condition |
|---|---|
400 | No fields provided, invalid titleField, form/comments on a non-collection model, or an enabled form with no exposed fields |
403 | Caller is not an owner/admin; the plan lacks forms.enabled / comments.enabled; or the plan's forms.models / comments.models limit is reached |
404 | Model not found |
Project Members
List Members
GET /api/workspaces/:workspaceId/projects/:projectId/membersReturns the project's members with their profiles. Returns 404 when the project is not in the workspace.
Add Member
POST /api/workspaces/:workspaceId/projects/:projectId/members| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address of the person to add. Existing users are looked up; new addresses are invited |
role | 'editor' | 'reviewer' | 'viewer' | Yes | Project role |
specificModels | boolean | No | Restrict access to specific models (Pro+) |
allowedModels | string[] | No | Model IDs the member can access |
If the person is not yet a workspace member, they are added to the workspace as a member first. Returns the created project member.
| Status | Condition |
|---|---|
400 | email or role missing, or an invalid role |
403 | Not an owner/admin; the reviewer / viewer role is not included in the plan; or the plan's team.members seat limit is reached |
404 | Project not found in the workspace |
Remove Member
DELETE /api/workspaces/:workspaceId/projects/:projectId/members/:memberIdReturns { "deleted": true }.
Auth
All three routes require workspace owner or admin role.
Project Activity
Paginated activity feed for a project, sourced from the workspace audit log.
GET /api/workspaces/:workspaceId/projects/:projectId/activityQuery Parameters
| Param | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
limit | number | 20 | Items per page (max 100) |
action | string | -- | Filter by action name (e.g. delete_project) |
sort | 'newest' | 'oldest' | newest | Sort order |
Response
{
"data": [
{
"id": "uuid",
"action": "save_content",
"actor": "uuid",
"entity": "content_entries",
"recordId": "uuid",
"origin": "chat",
"createdAt": "2026-01-01T00:00:00Z"
}
],
"total": 128,
"page": 1,
"limit": 20
}actor is the acting user's ID; entity is the affected table name.
Auth
Requires workspace owner, admin, or member role. Owners and admins see the whole workspace's audit log. A plain member must also be a member of this project (403 otherwise) and sees only the rows that name this project. Returns 404 if the project is not found in the workspace.
Project Receipts
The audit record of writes that ran under an approval, newest first. Each receipt carries the plan that ran, what it touched, who ran it, and the decisions that permitted it.
GET /api/workspaces/:workspaceId/projects/:projectId/receiptsQuery Parameters
| Param | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Rows to return (1-200) |
Response
{
"receipts": [
{
"id": "uuid",
"target": "contentrain",
"planHash": "…",
"createdAt": "2026-01-01T00:00:00Z",
"receipt": { }
}
]
}Auth
Any user with access to the project.
Chat Attachments
Convert files or links into content blocks before sending them with a chat message (see Chat). The client carries the returned blocks in the chat request body.
POST /api/workspaces/:workspaceId/projects/:projectId/attachmentsTwo request shapes:
- Links:
application/jsonwith{ "url": "https://..." }or{ "urls": ["https://..."] }. - Files:
multipart/form-datawith one or morefileparts and an optionalintentfield.intent=mediasaves images to the media library; any other value (or none) keeps them as temporary chat context.
At most 10 links or files per request, and 32 MB per file; a file over the size cap comes back with an error on its attachment entry instead of failing the request.
Response
{ "attachments": [ { "id": "att_…", "source": "upload", "filename": "brief.pdf", "mime": "application/pdf", "kind": "text", "blocks": [] } ] }Auth
Requires workspace owner, admin, or member role; a plain member must also belong to the project (403). Returns 400 when no link or file is supplied or the count limit is exceeded, and 404 if the project is not found.
Migrated Sites
These routes back the setup wizard that Studio shows for a project created from a migrated site (a repository delivered by Contentrain Migrate). The Studio app calls them; each is owner/admin only unless noted. They are internal and may change.
| Method | Path | Purpose |
|---|---|---|
GET | .../projects/:projectId/migration | Setup state: the delivery handoff, a summary, and where each setup step stands (done, waiting, needs_you, skipped) |
POST | .../migration/setup | Record a choice: { skip: step }, { unskip: step }, { liveSiteUrl }, or { seen: true } |
POST | .../migration/sync | Re-read the migration handoff from the repository |
POST | .../migration/site-binding | Bind the site's forms and comments to Studio |
GET | .../migration/comments-preview | Count and a short sample of the old site's comments |
POST | .../migration/import-comments | Import the old site's comments (safe to re-run) |
POST | .../migration/live-check | Commit a small test file so the live site can prove it serves the migrated build |
POST | .../migration/live-check/verify | Look for the test file on the live site ({ seen: boolean }) |
GET | .../migration/media | What moving the migrated images into Studio Media would take (counts, plan limits) |
POST | .../migration/media | Start the image import job |
POST | .../migration/media/apply | Point the site's image references at Studio Media once the import is done |
POST | .../migration/media/approve | Approve an image move held for review |
GET | .../migration/media/jobs/:jobId | Progress of an import job |
POST | .../migration/media/jobs/:jobId/resume | Resume an import paused because storage ran out |
.../ stands for /api/workspaces/:workspaceId/projects/:projectId.
GitHub Routes
These endpoints are used during the repository connection flow. They are not scoped under /api/workspaces/; they take workspaceId as a query parameter or body field, and all require a session. Every one needs the caller to be a workspace owner or admin (403 otherwise).
Get Installation
GET /api/github/installation?workspaceId=<id>Returns the GitHub App installation details for the workspace. workspaceId is required (400 without it).
{
"installed": true,
"installationId": 12345,
"account": { },
"selection": "selected",
"permissions": { },
"suspendedAt": null,
"repos": [ { "id": 1, "name": "my-website", "fullName": "org/my-website", "private": true, "language": "TypeScript" } ],
"settingsUrl": "https://github.com/settings/installations/12345"
}A workspace with no installation returns { "installed": false }. If the installation was removed or suspended on GitHub's side, the response is { installed: true, installationId, error: "installation_not_accessible", settingsUrl }.
List Repositories
GET /api/github/repos?workspaceId=<id>Lists repositories accessible through the workspace's GitHub App installation, each with id, fullName, name, owner, private, defaultBranch, description, language, and updatedAt. Returns 400 when workspaceId is missing or the workspace has no installation.
Scan Repository
GET /api/github/scan?workspaceId=<id>&owner=<owner>&repo=<repo>Scans a repository for a .contentrain/ directory and detects the framework stack. All three parameters are required (400 otherwise, also when the workspace has no installation). The response contains defaultBranch plus the framework detection result.
Create from Template
POST /api/github/create-from-templateCreates a new repository from a Contentrain starter template using the workspace's GitHub App installation.
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | Workspace whose installation creates the repository |
templateRepo | string | Yes | Template repository name, e.g. contentrain-starter-astro-blog |
name | string | Yes | New repository name (letters, digits, ., _, -; up to 100 characters; must start with a letter or digit) |
isPrivate | boolean | No | Create a private repository (default false) |
description | string | No | Repository description |
The response describes the new repository: id, fullName, name, owner, private, defaultBranch, description, htmlUrl, and needsAccess. needsAccess: true means the installation is limited to selected repositories and does not include the new one yet; the user must add it in their GitHub installation settings.
| Status | Condition |
|---|---|
400 | Missing parameters, invalid repository name, or no GitHub installation on the workspace |
403 | Not an owner/admin, or GitHub refused the creation |
422 | A repository with that name already exists |
GitHub App Setup
GET /api/github/setup?installation_id=<id>&state=<workspaceId>The redirect target GitHub calls after the App is installed. installation_id and state (the target workspace ID) are required (400 otherwise). On success the installation is stored on the workspace and the browser is redirected to /w/:slug. Errors: 403 if the caller has no GitHub-side access to the installation, 404 if the workspace is not found, 409 if the installation is already bound to another workspace.
List Available Installations
Enumerate GitHub App installations visible to the authenticated user, each annotated with whether it is already bound to a workspace (so the picker can disable in-use installations).
GET /api/github/installations/available?workspaceId=<id>Response
{
"installations": [
{
"id": 12345,
"account": "my-org",
"repositorySelection": "selected",
"targetType": "Organization",
"boundWorkspace": { "id": "uuid", "name": "Other Workspace", "slug": "other-workspace" }
}
]
}boundWorkspace is null when the installation is not yet connected to any workspace.
Auth
Requires workspace owner or admin role, and a valid GitHub user token.
Error Codes
| Status | Condition |
|---|---|
400 | Missing workspaceId |
401 | No usable GitHub user token -- response data.code is GITHUB_REAUTH_REQUIRED (user must reconnect GitHub) |
403 | Caller is not an owner/admin of the workspace |
404 | Workspace not found |
Connect Installation
Bind an existing GitHub App installation to a workspace -- the "Connect existing installation" counterpart to the install-callback flow. On success the workspace's github_installation_id is set and its status flips to active.
POST /api/github/installations/connectRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | Target workspace |
installationId | number | Yes | GitHub App installation ID |
Response
{ "connected": true, "installationId": 12345, "workspaceId": "uuid" }Auth
Requires workspace owner or admin role, and a valid GitHub user token. The caller's GitHub-side access to the installation is verified before binding.
Error Codes
| Status | Condition |
|---|---|
400 | Missing workspaceId or invalid installationId |
401 | No usable GitHub user token (data.code = GITHUB_REAUTH_REQUIRED) |
403 | Caller is not an owner/admin of the workspace, or lacks GitHub-side access to the installation |
404 | Workspace not found |
409 | Installation is already bound to a different workspace |
Related Pages
- Workspaces API -- workspace management
- Content API -- content operations within projects
- Deploy API -- deploy-hook settings and triggers
- Roles & Permissions -- project role definitions