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 all projects in a workspace.

GET /api/workspaces/:workspaceId/projects

Response

[
  {
    "id": "uuid",
    "name": "my-website",
    "repo_full_name": "org/my-website",
    "default_branch": "main",
    "content_root": "",
    "status": "active",
    "created_at": "2026-01-01T00:00:00Z"
  }
]

---

Create Project

Connect a GitHub repository as a new project.

POST /api/workspaces/:workspaceId/projects

Request Body

Field	Type	Required	Description
repoFullName	string	Yes	GitHub owner/repo full name
name	string	Yes	Display name for the project
defaultBranch	string	No	Default branch name (auto-detected if omitted)
contentRoot	string	No	Sub-path for .contentrain/ directory (e.g., apps/web)

Response

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

Error Codes

Status	Condition
403	Plan does not support project creation (projects.create)
409	Repository already connected in this workspace

---

Get Project

Get project details with member information.

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

---

Delete Project

Delete a project (does not delete the GitHub repository).

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

Auth

Requires workspace owner or admin role.

---

Update Project Configuration

Update the Contentrain configuration for a project (workflow, locales, etc.).

PATCH /api/workspaces/:workspaceId/projects/:projectId/config

Request 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

---

Project Health

Get project health status including branch health and GitHub connectivity.

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

---

Brain Sync

Refresh the project brain cache from Git.

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

Returns the full project snapshot: models, content, meta, and schema validation results.

---

Update Vocabulary

Update the project vocabulary (shared terminology across locales).

PATCH /api/workspaces/:workspaceId/projects/:projectId/vocabulary

Request Body

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

---

Update Model Metadata

Update model-level settings (e.g., form configuration).

PATCH /api/workspaces/:workspaceId/projects/:projectId/models/:modelId

---

Project Members

List Members

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

Add Member

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

Field	Type	Required	Description
userId	string	Yes	User ID (must be a workspace member)
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

Remove Member

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

Auth

Requires workspace owner or admin role to manage project members.

---

GitHub Routes

These endpoints are used during the repository connection flow.

Get Installation

GET /api/github/installation

Returns the GitHub App installation details for the current workspace.

List Repositories

GET /api/github/repos

Lists repositories accessible through the GitHub App installation.

Scan Repository

GET /api/github/scan?repo=owner/repo

Scans a repository for .contentrain/ directory and detects the framework stack.

Create from Template

POST /api/github/create-from-template

Creates a new repository from a starter kit template.

GitHub App Setup

GET /api/github/setup

Handles the GitHub App installation callback redirect.

Related Pages

• Workspaces API -- workspace management
• Content API -- content operations within projects
• Roles & Permissions -- project role definitions