Projects API

The Projects API manages organization projects through a stable external model. It does not expose Firestore paths, internal screen payloads, access materialization fields, or implementation metadata.

Roles

Operation	Member	Manager	Finance	HR
List and read projects	Yes	Yes	Financial fields only where permitted	Staffing fields only where permitted
Create or update projects	No	Yes	No	No
Archive or restore projects	No	Yes	No	No

Organization-wide-by-Role access means a permitted client may see all active projects allowed by its fields and Role, without project membership.

Project object

{
  "object": "project",
  "id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC",
  "code": "ACME-001",
  "name": "Acme implementation",
  "description": "Implement and launch Acme's operating workspace.",
  "status": "active",
  "start_date": "2026-08-01",
  "end_date": "2026-11-30",
  "customer_id": "com_01J8Q8VSMHH33D1FAMJNGHQCCM",
  "manager_member_id": "alice@example.com",
  "currency": "USD",
  "custom_fields": {},
  "created_at": "2026-07-20T12:00:00Z",
  "updated_at": "2026-08-22T09:45:00Z"
}

Organization-defined fields appear inside custom_fields and are described by the Custom Fields API.

List projects

GET /v1/projects

Operation ID: listProjects

Filters: status, customer_id, manager_member_id, start_date_gte, end_date_lte, search, sort, order, limit, and after.

Archived projects are excluded unless status=archived is requested.

Create a project

POST /v1/projects

Operation ID: createProject

Required Role: Manager. Required header: Idempotency-Key.

{
  "code": "ACME-001",
  "name": "Acme implementation",
  "description": "Implement and launch Acme's operating workspace.",
  "start_date": "2026-08-01",
  "end_date": "2026-11-30",
  "manager_member_id": "alice@example.com",
  "customer_id": "com_01J8Q8VSMHH33D1FAMJNGHQCCM",
  "custom_fields": {}
}

The server assigns id, audit fields, access materialization, and initial status. References must belong to the same organization and must not be deleted.

Get a project

GET /v1/projects/{project_id}

Operation ID: getProject

Returns ETag for concurrency control.

Update a project

PATCH /v1/projects/{project_id}

Operation ID: updateProject

Required Role: Manager. Use If-Match with the current ETag.

Immutable fields such as id, organization, creation audit fields, and internal access data are ignored only where explicitly documented; otherwise they produce IMMUTABLE_FIELD.

Archive a project

POST /v1/projects/{project_id}/archive

Operation ID: archiveProject

Required Role: Manager. Required header: Idempotency-Key.

Archiving is the v1 deletion model. It preserves audit history and dependent records. Eos returns 409 when an active workflow prevents archival.

Restore a project

POST /v1/projects/{project_id}/restore

Operation ID: restoreProject

Required Role: Manager. Restores an archived project when its dependencies remain valid.

Common errors

PROJECT_CODE_CONFLICT, PROJECT_NOT_FOUND, INVALID_MANAGER, INVALID_CUSTOM_FIELD, STALE_RESOURCE, and PROJECT_ARCHIVE_BLOCKED.

Next: Tasks API.