Projects

Projects organize entities, documents, tasks, and workflows within an organization.

List Projects

GET /v1/projects

Lists projects in the caller's active organization. The organization is taken from the authenticated session; it is not passed as a parameter.

Query Parameters

Parameter	Type	Description
`limit`	integer	Max results per page (default 50, max 100)
`offset`	integer	Pagination offset

Response

{
  "success": true,
  "data": [
    {
      "id": "...",
      "name": "My Project",
      "slug": "my-project",
      "is_active": true,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Create Project

POST /v1/projects

Request Body

{
  "name": "My Project",
  "description": "Optional project description"
}

The project is created in the caller's active organization; do not send an org_id in the body. An optional slug may be supplied; otherwise it is derived from the name. Do not send id, created_at, or updated_at; these are assigned automatically. Project IDs use UUIDv7 format.

Response

Returns 201 Created with the complete project record. The caller is recorded as the project owner and the project starts active.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "name": "My Project",
    "slug": "my-project",
    "description": "Optional project description",
    "prefix": null,
    "visibility": "private",
    "category_id": null,
    "owner_scope": "...",
    "is_active": true,
    "created_by_user_id": "...",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "settings": {}
  }
}

Response Codes

Status	Meaning
`201`	Project created; the full record is returned
`400`	Validation error: missing/invalid `name`, an invalid or reserved `slug`, or a malformed `category_id`
`401`	Missing or invalid access token
`403`	Caller lacks the permission to create projects, or the organization's project limit has been reached
`409`	A project with the supplied slug already exists in this organization
`500`	Unexpected server error

Get Project

GET /v1/projects/:projectId

Response

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "name": "My Project",
    "slug": "my-project",
    "description": "...",
    "is_active": true,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-16T14:30:00Z"
  }
}

Update Project

PUT /v1/projects/:projectId

Request Body

{
  "name": "Updated Project Name",
  "description": "Updated description"
}

Delete Project

DELETE /v1/projects/:projectId

Soft delete: marks the project inactive rather than removing it. The project data is retained; restore it by updating the project with is_active: true.