Tasks

A task is something someone said they would do: call a buyer back, chase a title, prepare a car for its sale window. In Cypress the same task list serves people, automations and agents, so an agent your organization connects can be given work, report it done, and hand work to a person. Since 1.5.0.

Every write goes through the same task commands the app uses, so the rules are the app's rules whoever calls:

• A task belongs to something of your organization: a contact, a company, a deal, a vehicle, a sell goal, window or lot, or a buy target. A task about nothing is refused (422 INVALID), and a record of another organization answers 404 NOT_FOUND exactly as an unknown one does.
• It is given only to an active member of your organization, people and agents alike (422 INVALID, "That person cannot be given this task.").
• It says who made it and from where. An agent's task is its own (source: AGENT, with its playKey); an app acting for a person makes the person's (PERSON); an API key has no person behind it, so its task reads as an automation's (AUTOMATION), made by nobody and unassigned unless the request names someone.

Both an API key and a Connect Cypress token are accepted.

The task

{
  "id": "clx…",
  "title": "Call the buyer back about the RAV4",
  "notes": null,
  "status": "OPEN",
  "dueDate": "2026-11-02T15:00:00.000Z",
  "channel": "PHONE",
  "source": "AGENT",
  "playKey": "follow-up",
  "assignee": { "id": "clx…", "name": "Scout", "kind": "AGENT" },
  "createdBy": { "id": "clx…", "name": "Scout", "kind": "AGENT" },
  "completedBy": null,
  "completedAt": null,
  "links": {
    "contactId": "clx…", "dealId": null, "businessId": null, "vehicleId": "clx…",
    "planningGoalId": null, "saleWindowKey": null, "lotKey": null, "buyTargetId": null, "plan": null,
    "app": "https://app.getcypress.ai/go/task/clx…"
  },
  "createdOn": "2026-10-15T14:00:00.000Z",
  "updatedOn": "2026-10-15T14:00:00.000Z",
  "href": "/api/v1/tasks/clx…"
}

People are named and marked PERSON or AGENT, never emailed: tasks:read is not members:read. saleWindowKey is a sale window's lineage (2026W44-2026W45), which outlives the plan's versions. plan is a quarter's plan as a whole, { "side": "SELL", "periodKey": "2026-Q4" } ("get Q4 approved"): send it on create to put a task there (Cypress's own book has no plan, so it is refused there). The plan's Tasks tab in the app lists these beside the tasks on its goals, windows, lots and targets.

List and read

GET /api/v1/tasks returns your organization's tasks, soonest due first and undated last, 25 to a page (limit up to 100, offset, nextHref). Filters combine:

An unknown filter is refused with 422, so a typo never returns everything. assignee=me needs a token: an API key acts as nobody (422).

curl "$BASE/api/v1/tasks?assignee=me&status=OPEN" -H "authorization: Bearer $TOKEN"

GET /api/v1/tasks/{id} returns one task.

Write

curl -X POST "$BASE/api/v1/tasks" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -H "Idempotency-Key: follow-up-con_123-2026-11-02" \
  -d '{
    "title": "Call the buyer back about the RAV4",
    "contactId": "clx…",
    "vehicleId": "clx…",
    "dueDate": "2026-11-02T15:00:00Z",
    "channel": "PHONE",
    "playKey": "follow-up"
  }'

Dry runs. Every write takes ?dryRun=true: the rules are checked and the answer is { "dryRun": true, "changes": { … } }, the fields it would set, with nothing written and no event sent.

Idempotency keys. Send Idempotency-Key (up to 200 characters) and a retry with the same key and body gets the first answer, with Idempotent-Replayed: true, instead of a second task. The same key with a different body is 422 IDEMPOTENCY_KEY_REUSED.

Writes send the task events: TASK.CREATED, TASK.ASSIGNED when a task is handed to someone other than the caller, TASK.COMPLETED and TASK.CANCELLED. Editing, reopening and removing send nothing.