Skip to content

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/projects

Response ​

A plain array of project rows (not paginated).

json
[
  {
    "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/projects

Request Body ​

FieldTypeRequiredDescription
repoFullNamestringYesGitHub owner/repo full name
defaultBranchstringNoDefault branch name (defaults to main when omitted -- it is not auto-detected)
contentRootstringNoSub-path for .contentrain/ directory (e.g., apps/web); stored as / when omitted
detectedStackstringNoFramework detected by Scan Repository
hasContentrainbooleanNoPass 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.

json
{
  "id": "uuid",
  "repo_full_name": "org/my-website",
  "default_branch": "main",
  "content_root": "/",
  "status": "active"
}

Error Codes ​

StatusCondition
400repoFullName missing
402The workspace is on the free plan -- a paid plan is required to connect repositories. data is { requiresCheckout: true, workspaceId }
409Repository 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)
502The content branch could not be prepared (data.code content_branch_failed)

Get Project ​

Get project details with member information.

GET /api/workspaces/:workspaceId/projects/:projectId

Response ​

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

Removes 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/config

Request Body ​

FieldTypeRequiredDescription
workflow'auto-merge' | 'review'NoContent workflow mode
localesobjectNoLocale configuration with default and supported
domainsstring[]NoContent domains

Only the supplied fields change; locales.default and locales.supported are merged individually.

Response ​

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

StatusCondition
403Not an owner/admin, or workflow: 'review' on a plan without workflow.review
404.contentrain/config.json not found in the repository
422The 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/health

Response ​

json
{
  "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/sync

Query Parameters ​

ParamTypeRequiredDescription
treeShastringNoTree 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/vocabulary

Request Body ​

json
{
  "terms": {
    "brand_name": {
      "en": "Contentrain",
      "tr": "Contentrain"
    }
  }
}

Response ​

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

StatusCondition
400terms missing or not an object
403Caller cannot save content
409The write kept conflicting with concurrent edits after 3 attempts (retry)
502vocabulary.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/:modelId

Request Body ​

At least one of the following (400 otherwise):

FieldTypeDescription
formobjectPartial form configuration (enabled, public, exposedFields, requiredOverrides, honeypot, captcha, successMessage, limits, autoApprove, notifications). Merged with the existing form config. See Forms
commentsobjectPartial comments configuration, merged with the existing one. See Comments
titleFieldstringField 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 ​

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

StatusCondition
400No fields provided, invalid titleField, form/comments on a non-collection model, or an enabled form with no exposed fields
403Caller is not an owner/admin; the plan lacks forms.enabled / comments.enabled; or the plan's forms.models / comments.models limit is reached
404Model not found

Project Members ​

List Members ​

GET /api/workspaces/:workspaceId/projects/:projectId/members

Returns 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
FieldTypeRequiredDescription
emailstringYesEmail address of the person to add. Existing users are looked up; new addresses are invited
role'editor' | 'reviewer' | 'viewer'YesProject role
specificModelsbooleanNoRestrict access to specific models (Pro+)
allowedModelsstring[]NoModel 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.

StatusCondition
400email or role missing, or an invalid role
403Not an owner/admin; the reviewer / viewer role is not included in the plan; or the plan's team.members seat limit is reached
404Project not found in the workspace

Remove Member ​

DELETE /api/workspaces/:workspaceId/projects/:projectId/members/:memberId

Returns { "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/activity

Query Parameters ​

ParamTypeDefaultDescription
pagenumber1Page number
limitnumber20Items per page (max 100)
actionstring--Filter by action name (e.g. delete_project)
sort'newest' | 'oldest'newestSort order

Response ​

json
{
  "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/receipts

Query Parameters ​

ParamTypeDefaultDescription
limitnumber50Rows to return (1-200)

Response ​

json
{
  "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/attachments

Two request shapes:

  • Links: application/json with { "url": "https://..." } or { "urls": ["https://..."] }.
  • Files: multipart/form-data with one or more file parts and an optional intent field. intent=media saves 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 ​

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

MethodPathPurpose
GET.../projects/:projectId/migrationSetup state: the delivery handoff, a summary, and where each setup step stands (done, waiting, needs_you, skipped)
POST.../migration/setupRecord a choice: { skip: step }, { unskip: step }, { liveSiteUrl }, or { seen: true }
POST.../migration/syncRe-read the migration handoff from the repository
POST.../migration/site-bindingBind the site's forms and comments to Studio
GET.../migration/comments-previewCount and a short sample of the old site's comments
POST.../migration/import-commentsImport the old site's comments (safe to re-run)
POST.../migration/live-checkCommit a small test file so the live site can prove it serves the migrated build
POST.../migration/live-check/verifyLook for the test file on the live site ({ seen: boolean })
GET.../migration/mediaWhat moving the migrated images into Studio Media would take (counts, plan limits)
POST.../migration/mediaStart the image import job
POST.../migration/media/applyPoint the site's image references at Studio Media once the import is done
POST.../migration/media/approveApprove an image move held for review
GET.../migration/media/jobs/:jobIdProgress of an import job
POST.../migration/media/jobs/:jobId/resumeResume 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).

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

Creates a new repository from a Contentrain starter template using the workspace's GitHub App installation.

FieldTypeRequiredDescription
workspaceIdstringYesWorkspace whose installation creates the repository
templateRepostringYesTemplate repository name, e.g. contentrain-starter-astro-blog
namestringYesNew repository name (letters, digits, ., _, -; up to 100 characters; must start with a letter or digit)
isPrivatebooleanNoCreate a private repository (default false)
descriptionstringNoRepository 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.

StatusCondition
400Missing parameters, invalid repository name, or no GitHub installation on the workspace
403Not an owner/admin, or GitHub refused the creation
422A 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 ​

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

StatusCondition
400Missing workspaceId
401No usable GitHub user token -- response data.code is GITHUB_REAUTH_REQUIRED (user must reconnect GitHub)
403Caller is not an owner/admin of the workspace
404Workspace 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/connect

Request Body ​

FieldTypeRequiredDescription
workspaceIdstringYesTarget workspace
installationIdnumberYesGitHub App installation ID

Response ​

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

StatusCondition
400Missing workspaceId or invalid installationId
401No usable GitHub user token (data.code = GITHUB_REAUTH_REQUIRED)
403Caller is not an owner/admin of the workspace, or lacks GitHub-side access to the installation
404Workspace not found
409Installation is already bound to a different workspace

Released under the AGPL-3.0 License. Privacy