API reference

Projects

Users own Projects. Creating a Project creates an owner membership for the requesting User. The first Project owned by a User becomes its default; later Projects require X-Project-ID when the User needs to select one for execution placement.

Projects select placement for Pipeline and Activity runs. Model and Harness defaults belong to User settings; Pipeline, Activity, and loop-agent configuration can define narrower persisted overrides.

Project calls

List projects

GET /api/v1/projects returns every Project accessible to the User identified by X-User-ID. The default Project appears first.

GET /api/v1/projects
X-User-ID: user-123

Example response (200 OK):

[
  {
    "id": "project-acme",
    "name": "Acme",
    "created_at": "2026-08-26T10:00:00Z",
    "updated_at": "2026-08-26T10:00:00Z"
  }
]

Create project

POST /api/v1/projects creates a Project owned by the User identified by X-User-ID. The User must first be registered through POST /api/v1/users.

POST /api/v1/projects
X-User-ID: user-123
Content-Type: application/json

{
  "name": "Acme"
}

Example response (201 Created):

{
  "id": "project-acme",
  "name": "Acme",
  "created_at": "2026-08-26T10:00:00Z",
  "updated_at": "2026-08-26T10:00:00Z"
}

Describe project

GET /api/v1/projects/{project_id} returns one Project accessible to the User identified by X-User-ID.

GET /api/v1/projects/project-acme
X-User-ID: user-123

Example response (200 OK):

{
  "id": "project-acme",
  "name": "Acme",
  "created_at": "2026-08-26T10:00:00Z",
  "updated_at": "2026-08-26T10:00:00Z"
}

Update project

PATCH /api/v1/projects/{project_id} updates mutable metadata for one Project accessible to the User identified by X-User-ID. Currently, name is the only mutable field, and it must be supplied with a non-empty value.

PATCH /api/v1/projects/project-acme
X-User-ID: user-123
Content-Type: application/json

{
  "name": "Acme Platform"
}

Example response (200 OK):

{
  "id": "project-acme",
  "name": "Acme Platform",
  "created_at": "2026-08-26T10:00:00Z",
  "updated_at": "2026-08-26T10:15:00Z"
}