Work with a shared context
A project groups ongoing work, participants, activity, and tasks without copying contact or organisation records.
{
"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.