# Projects

> Track shared work and the people involved.

## Work with a shared context

A project groups ongoing work, participants, activity, and tasks without copying contact or organisation records.

```json
{
  "name": "Autumn research",
  "status": "active",
  "target_date": "2026-11-30",
  "tags": ["research"],
  "idempotency_key": "autumn-project-001"
}
```

Call `projects_create`. `name` and `idempotency_key` are required. Other fields are `description`, `status`, `target_date`, `tags`, `external_references`, and registered `custom_fields`. Dates use `YYYY-MM-DD`. An exact active name match requires reviewing candidates before `allow_duplicate: true`.

## Status and lifecycle

Statuses are `planned` (default), `active`, `on_hold`, `completed`, and `cancelled`. A project status is an organisational label; changing it does not complete tasks, run agents, or perform external actions.

Use `projects_update` with `id`, `expected_revision`, `idempotency_key`, and a `changes` object. Null clears the optional target date or description. Standard array replacement and custom-field patch rules apply.

`projects_archive` and `projects_restore` retain the record and its relationships. Both require a current revision and operation key. Archived projects are hidden by default; restore before editing or creating new links.

## Search and retrieve

`projects_search` supports literal name/ID `query`, exact `status` and `tag`, participant `contact_id` or `organisation_id`, scalar `custom_fields`, `include_archived`, `page`, and `per_page`. Filters combine with AND. `projects_get` retrieves one ID.

## Participants and briefs

Use `participants_set` to link a contact or organisation with a project-specific role and context. A repeated identical addition reuses the participant; changes require its ID and revision.

`projects_brief` returns the project, participants, directly linked activity with sources, and outstanding directly linked tasks. Each section defaults to five records; use `per_section` (maximum 20) and the separate `activity_page`, `task_page`, and `relationship_page` cursors to continue. These are page numbers and may shift under concurrent writes.

The brief does not silently include every activity or task of every participant. Link an entry to the project explicitly when it belongs in that project's context.

## Choose result order

Search accepts `sort`: `name`, `target_date`, `created_at`, or `updated_at`, with `direction`: `asc` (default) or `desc`. The first field is the default. ID ascending breaks ties; nullable dates sort last. Only these field names are accepted.