# Tasks Manage tasks. Tasks can be assigned to users and linked to companies, contacts, and deals. ## List tasks > Returns tasks the user has access to. Filter by workspace using the \`where\` parameter: \`{"workspaceId": "\"}\`.\ > \ > Common filters:\ > \- Open tasks: \`{"workspaceId": "\", "done": false}\`\ > \- Tasks for a contact: \`{"workspaceId": "\", "contactIds": {"$overlaps": \["\"]}}\`\ > \- Tasks by deadline: \`{"workspaceId": "\", "deadline": {"$gte": "now()"}}\`
````json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.5.0"},"tags":[{"name":"Tasks","description":"Manage tasks. Tasks can be assigned to users and linked to companies, contacts, and deals."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Create an API key from [Workspace Settings → API keys](https://app.zero.inc/settings/workspace/api)."}},"parameters":{"fields":{"name":"fields","in":"query","description":"Comma-separated list of fields to return. Defaults to all fields.","schema":{"type":"string"}},"where":{"name":"where","in":"query","description":"JSON-encoded filter object. All top-level conditions are combined with AND logic. Use `$or` for OR logic.\n\nThe available operators depend on the **data type** of the field you are filtering on.\n\n---\n\n## String fields\nFields like `name`, `domain`, `description`, `linkedin`, `source`, `externalId`, `location`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"name\": \"Linear\"}` |\n| `$eq` | Explicit exact match | `{\"name\": {\"$eq\": \"Linear\"}}` |\n| `$not` | Not equal | `{\"source\": {\"$not\": \"import\"}}` |\n| `$in` | Matches any value in array | `{\"domain\": {\"$in\": [\"linear.app\", \"granola.so\"]}}` |\n| `$notIn` | Matches none of the values | `{\"source\": {\"$notIn\": [\"import\", \"api\"]}}` |\n| `$contains` | Case-insensitive word-boundary substring match | `{\"name\": {\"$contains\": \"YC\"}}` |\n| `$notContains` | Does not contain | `{\"name\": {\"$notContains\": \"Test\"}}` |\n| `$containsAny` | Contains any of the given strings | `{\"name\": {\"$containsAny\": [\"YC\", \"Techstars\"]}}` |\n| `$startsWith` | Starts with prefix | `{\"domain\": {\"$startsWith\": \"app.\"}}` |\n| `$endsWith` | Ends with suffix | `{\"email\": {\"$endsWith\": \"@zero.inc\"}}` |\n| `$exists` | Field is present and truthy | `{\"linkedin\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent, null, or empty | `{\"linkedin\": {\"$notExists\": true}}` |\n\n---\n\n## Number fields\nFields like `value`, `confidence`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"value\": 5000}` |\n| `$eq` | Explicit exact match | `{\"value\": {\"$eq\": 5000}}` |\n| `$not` | Not equal | `{\"value\": {\"$not\": 0}}` |\n| `$gt` | Greater than | `{\"value\": {\"$gt\": 10000}}` |\n| `$gte` | Greater than or equal | `{\"value\": {\"$gte\": 5000}}` |\n| `$lt` | Less than | `{\"value\": {\"$lt\": 10000}}` |\n| `$lte` | Less than or equal | `{\"value\": {\"$lte\": 50000}}` |\n| `$in` | Matches any value in array | `{\"confidence\": {\"$in\": [0.25, 0.5, 0.75]}}` |\n| `$notIn` | Matches none of the values | `{\"confidence\": {\"$notIn\": [0, 1]}}` |\n| `$exists` | Field is present and truthy | `{\"value\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent, null, or zero | `{\"value\": {\"$notExists\": true}}` |\n\nMultiple operators can be combined on one field:\n```json\n{\"value\": {\"$gte\": 5000, \"$lt\": 10000}}\n```\n\n---\n\n## Date fields\nFields like `closeDate`, `startDate`, `endDate`, `createdAt`, `updatedAt`.\n\nValues can be ISO 8601 strings (`\"2026-01-01\"`, `\"2026-01-01T00:00:00Z\"`) or **relative time macros**.\n\n**Relative time macros:** `+Nd` / `-Nd` (days), `+Nw` / `-Nw` (weeks), `+Nm` / `-Nm` (months), `+Ny` / `-Ny` (years), `+Nh` / `-Nh` (hours), `+Ns` / `-Ns` (seconds), `now()`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$gte` | On or after | `{\"closeDate\": {\"$gte\": \"2026-01-01\"}}` |\n| `$lte` | On or before | `{\"closeDate\": {\"$lte\": \"2026-03-31\"}}` |\n| `$gt` | After | `{\"createdAt\": {\"$gt\": \"2026-01-01T00:00:00Z\"}}` |\n| `$lt` | Before | `{\"createdAt\": {\"$lt\": \"now()\"}}` |\n| `$date` | Exact date match (compares date portion only) | `{\"closeDate\": {\"$date\": \"2026-01-15\"}}` |\n| `$exists` | Field is present and truthy | `{\"closeDate\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent or null | `{\"closeDate\": {\"$notExists\": true}}` |\n\nDate range example:\n```json\n{\"closeDate\": {\"$gte\": \"2026-01-01\", \"$lte\": \"2026-03-31\"}}\n```\nRelative date example (closing in next 30 days):\n```json\n{\"closeDate\": {\"$gte\": \"now()\", \"$lte\": \"+30d\"}}\n```\n\n---\n\n## Array fields\nFields like `listIds`, `ownerIds`, `contactIds`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$includes` | Array contains the given value (use this — bare exact match is not supported) | `{\"listIds\": {\"$includes\": \"\"}}` |\n| `$notIncludes` | Array does not contain the given value | `{\"ownerIds\": {\"$notIncludes\": \"\"}}` |\n| `$overlaps` | Array contains at least one of the given values | `{\"ownerIds\": {\"$overlaps\": [\"\", \"\"]}}` |\n| `$notOverlaps` | Array contains none of the given values | `{\"listIds\": {\"$notOverlaps\": [\"\", \"\"]}}` |\n| `$all` | Array contains all of the given values | `{\"listIds\": {\"$all\": [\"\", \"\"]}}` |\n| `$length` | Filter by array length (supports nested operators) | `{\"contactIds\": {\"$length\": {\"$gte\": 2}}}` |\n| `$exists` | Field is present and non-empty | `{\"ownerIds\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent or empty | `{\"ownerIds\": {\"$notExists\": true}}` |\n\n---\n\n## UUID / ID fields\nFields like `id`, `workspaceId`, `companyId`, `stage`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"stage\": \"\"}` |\n| `$in` | Matches any value in array | `{\"stage\": {\"$in\": [\"\", \"\"]}}` |\n| `$notIn` | Matches none of the values | `{\"stage\": {\"$notIn\": [\"\"]}}` |\n| `$not` | Not equal | `{\"stage\": {\"$not\": \"\"}}` |\n\n---\n\n## Boolean fields\nFields like `archived`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"archived\": false}` |\n| `$not` | Not equal | `{\"archived\": {\"$not\": true}}` |\n\n---\n\n## Logical operators\nThese work across all data types.\n\n`$or` — matches if **any** sub-condition is true:\n```json\n{\n \"workspaceId\": \"\",\n \"$or\": [\n {\"ownerIds\": {\"$overlaps\": [\"\", \"\"]}},\n {\"closeDate\": {\"$gte\": \"2026-01-01\"}}\n ]\n}\n```\n\n`$and` — matches if **all** sub-conditions are true (useful when you need multiple conditions on the same field):\n```json\n{\n \"$and\": [\n {\"name\": {\"$contains\": \"Enterprise\"}},\n {\"name\": {\"$notContains\": \"Test\"}}\n ]\n}\n```\n\n---\n\n## Dot-notation (relation filtering)\nUse dot-syntax to filter records based on properties of related objects:\n```json\n{\"company.name\": \"Linear\"}\n{\"company.domain\": {\"$in\": [\"linear.app\", \"granola.so\"]}}\n{\"company.location.city\": \"San Francisco\"}\n{\"companyProfile.categories\": {\"$overlaps\": [\"Sales\", \"Marketing\"]}}\n```\nAll operators available for the target field's data type can be used with dot-notation.\n\n---\n\n## Custom property filtering\nCustom properties are stored in the `custom` object on records, keyed by UUID. Use `GET /api/columns` to discover the available custom property IDs, types, and options for a workspace.\n\nFilter on custom properties using `custom.` with operators appropriate for the column's type.\n\n> **Note:** For `select` and `multiselect` columns, option values are UUIDs (the `key` field from the column's `options` array). Use the UUID, not the human-readable name.\n\n```json\n// Text custom property\n{\"custom.54e1ca7d-69c3-4b77-8266-8085b5834116\": {\"$contains\": \"enterprise\"}}\n\n// Select custom property (use the option key UUID)\n{\"custom.a1b2c3d4-e5f6-7890-abcd-ef1234567890\": \"3e839b5c-b311-4887-b2da-727d2d75cdd6\"}\n\n// Multi-select custom property (use option key UUIDs)\n{\"custom.b2c3d4e5-f6a7-8901-bcde-f12345678901\": {\"$overlaps\": [\"a1b1c1d1-e1f1-1111-aaaa-111111111111\", \"b2b2c2d2-e2f2-2222-bbbb-222222222222\"]}}\n\n// Currency/number custom property\n{\"custom.c3d4e5f6-a7b8-9012-cdef-123456789012\": {\"$gte\": 100000}}\n\n// Date custom property\n{\"custom.d4e5f6a7-b8c9-0123-defa-234567890123\": {\"$gte\": \"2026-01-01\"}}\n\n// Boolean custom property\n{\"custom.e5f6a7b8-c9d0-1234-efab-345678901234\": true}\n\n// Check if custom property has a value\n{\"custom.f6a7b8c9-d0e1-2345-fabc-456789012345\": {\"$exists\": true}}\n```\n\n---\n\n## Complex example\nAll top-level keys are ANDed together:\n```json\n{\n \"name\": {\"$contains\": \"Zero\"},\n \"location.city\": \"Helsinki\",\n \"location.country\": {\"$in\": [\"United Kingdom\", \"Germany\", \"Sweden\"]},\n \"value\": {\"$gte\": 10000},\n \"closeDate\": {\"$gte\": \"2026-01-01\", \"$lte\": \"2026-03-31\"},\n \"ownerIds\": {\"$includes\": \"\"},\n \"stage\": {\"$in\": [\"\", \"\"]},\n \"lastActivity\": {\"$exists\": true},\n \"companyProfile.categories\": {\"$overlaps\": [\"Sales\", \"Marketing\"]},\n \"custom.54e1ca7d-69c3-4b77-8266-8085b5834116\": {\"$contains\": \"enterprise\"}\n}\n```\n","schema":{"type":"string"}},"limit":{"name":"limit","in":"query","description":"Maximum number of records to return","schema":{"type":"integer","default":100}},"offset":{"name":"offset","in":"query","description":"Pagination offset","schema":{"type":"integer","default":0}},"orderBy":{"name":"orderBy","in":"query","description":"JSON string for sort order","schema":{"type":"string"}}},"schemas":{"Task":{"type":"object","description":"A task that can be assigned to users and linked to companies, contacts, and deals.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Title of the task"},"done":{"type":"boolean","description":"Whether the task has been completed","default":false},"priority":{"type":"integer","nullable":true,"description":"Task priority level.\n- `null` — No priority\n- `1` — Low\n- `2` — Medium\n- `3` — High\n- `4` — Urgent\n","enum":[null,1,2,3,4]},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Due date and time (ISO 8601)"},"content":{"type":"object","description":"Task title as a Tiptap document. Auto-generated from `name` if not provided on creation."},"description":{"type":"object","description":"Extended notes or context for the task, in Tiptap document format. Supports rich formatting."},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Companies linked to this task"},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Contacts linked to this task"},"dealIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Deals linked to this task"},"assignedToIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"User IDs this task is assigned to"},"type":{"type":"string","nullable":true,"description":"Set automatically by integrations (e.g. `circleback` for meeting-generated tasks, `ai-generated` for AI-created tasks). Not intended to be set manually via the API.\n"},"message":{"type":"string","nullable":true},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdById":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"source":{"type":"string","nullable":true}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/tasks":{"get":{"tags":["Tasks"],"summary":"List tasks","description":"Returns tasks the user has access to. Filter by workspace using the `where` parameter: `{\"workspaceId\": \"\"}`.\n\nCommon filters:\n- Open tasks: `{\"workspaceId\": \"\", \"done\": false}`\n- Tasks for a contact: `{\"workspaceId\": \"\", \"contactIds\": {\"$overlaps\": [\"\"]}}`\n- Tasks by deadline: `{\"workspaceId\": \"\", \"deadline\": {\"$gte\": \"now()\"}}`\n","operationId":"listTasks","parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/where"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/orderBy"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Create a task > Create a new task in a workspace.\ > \ > \### content vs description\ > \ > Tasks have two Tiptap fields with distinct purposes:\ > \ > \- \*\*\`content\`\*\* — The task title as a Tiptap document. If omitted, it is automatically generated from the \`name\` field.\ > \- \*\*\`description\`\*\* — Extended notes or context for the task. Supports rich formatting including headings, bullet lists, and task lists. Optional.\ > \ > \### Tiptap document format\ > \ > Both \`content\` and \`description\` use the same Tiptap document structure:\ > \ > \`\`\`json\ > {\ > "type": "doc",\ > "content": \[\ > {\ > "type": "paragraph",\ > "content": \[{"type": "text", "text": "Your text here"}]\ > }\ > ]\ > }\ > \`\`\`\ > \ > Rich formatting example with headings, bold text, bullet lists and task lists:\ > \ > \`\`\`json\ > {\ > "type": "doc",\ > "content": \[\ > {\ > "type": "heading",\ > "attrs": {"level": 3},\ > "content": \[{"type": "text", "text": "Goal"}]\ > },\ > {\ > "type": "paragraph",\ > "content": \[\ > {"type": "text", "text": "Complete the "},\ > {"type": "text", "text": "onboarding proposal", "marks": \[{"type": "bold"}]},\ > {"type": "text", "text": " before Friday."}\ > ]\ > },\ > {\ > "type": "taskList",\ > "content": \[\ > {\ > "type": "taskItem",\ > "attrs": {"checked": false},\ > "content": \[{"type": "paragraph", "content": \[{"type": "text", "text": "Review requirements"}]}]\ > },\ > {\ > "type": "taskItem",\ > "attrs": {"checked": false},\ > "content": \[{"type": "paragraph", "content": \[{"type": "text", "text": "Draft document"}]}]\ > }\ > ]\ > },\ > {\ > "type": "bulletList",\ > "content": \[\ > {\ > "type": "listItem",\ > "content": \[{"type": "paragraph", "content": \[{"type": "text", "text": "Keep it concise"}]}]\ > }\ > ]\ > }\ > ]\ > }\ > \`\`\`\ > \ > \### Priority\ > \ > \| Value | Label |\ > \|-------|-------|\ > \| \`null\` | No priority |\ > \| \`1\` | Low |\ > \| \`2\` | Medium |\ > \| \`3\` | High |\ > \| \`4\` | Urgent |\ > \ > \### Linking records\ > \ > Tasks can be linked to multiple companies, contacts, and deals simultaneously via \`companyIds\`, \`contactIds\`, and \`dealIds\`.\ > \ > \> \*\*⚠️ Important:\*\* When updating array fields via \`PATCH\`, the entire array is \*\*replaced\*\* — not merged. Always include all desired IDs when patching these fields.
````json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.5.0"},"tags":[{"name":"Tasks","description":"Manage tasks. Tasks can be assigned to users and linked to companies, contacts, and deals."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Create an API key from [Workspace Settings → API keys](https://app.zero.inc/settings/workspace/api)."}},"schemas":{"TaskCreate":{"type":"object","required":["workspaceId","name"],"properties":{"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Title of the task. Also used to auto-generate `content` if `content` is not provided."},"content":{"type":"object","description":"Task title as a Tiptap document. If omitted, auto-generated from `name`."},"description":{"type":"object","description":"Extended notes in Tiptap document format. Supports headings, bullet lists, task lists, and inline formatting."},"done":{"type":"boolean","default":false},"priority":{"type":"integer","nullable":true,"description":"`null` = No priority, `1` = Low, `2` = Medium, `3` = High, `4` = Urgent","enum":[null,1,2,3,4]},"deadline":{"type":"string","format":"date-time"},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"}},"dealIds":{"type":"array","items":{"type":"string","format":"uuid"}},"assignedToIds":{"type":"array","items":{"type":"string","format":"uuid"}},"externalId":{"type":"string"},"source":{"type":"string"}}},"Task":{"type":"object","description":"A task that can be assigned to users and linked to companies, contacts, and deals.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Title of the task"},"done":{"type":"boolean","description":"Whether the task has been completed","default":false},"priority":{"type":"integer","nullable":true,"description":"Task priority level.\n- `null` — No priority\n- `1` — Low\n- `2` — Medium\n- `3` — High\n- `4` — Urgent\n","enum":[null,1,2,3,4]},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Due date and time (ISO 8601)"},"content":{"type":"object","description":"Task title as a Tiptap document. Auto-generated from `name` if not provided on creation."},"description":{"type":"object","description":"Extended notes or context for the task, in Tiptap document format. Supports rich formatting."},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Companies linked to this task"},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Contacts linked to this task"},"dealIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Deals linked to this task"},"assignedToIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"User IDs this task is assigned to"},"type":{"type":"string","nullable":true,"description":"Set automatically by integrations (e.g. `circleback` for meeting-generated tasks, `ai-generated` for AI-created tasks). Not intended to be set manually via the API.\n"},"message":{"type":"string","nullable":true},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdById":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"source":{"type":"string","nullable":true}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/tasks":{"post":{"tags":["Tasks"],"summary":"Create a task","description":"Create a new task in a workspace.\n\n### content vs description\n\nTasks have two Tiptap fields with distinct purposes:\n\n- **`content`** — The task title as a Tiptap document. If omitted, it is automatically generated from the `name` field.\n- **`description`** — Extended notes or context for the task. Supports rich formatting including headings, bullet lists, and task lists. Optional.\n\n### Tiptap document format\n\nBoth `content` and `description` use the same Tiptap document structure:\n\n```json\n{\n \"type\": \"doc\",\n \"content\": [\n {\n \"type\": \"paragraph\",\n \"content\": [{\"type\": \"text\", \"text\": \"Your text here\"}]\n }\n ]\n}\n```\n\nRich formatting example with headings, bold text, bullet lists and task lists:\n\n```json\n{\n \"type\": \"doc\",\n \"content\": [\n {\n \"type\": \"heading\",\n \"attrs\": {\"level\": 3},\n \"content\": [{\"type\": \"text\", \"text\": \"Goal\"}]\n },\n {\n \"type\": \"paragraph\",\n \"content\": [\n {\"type\": \"text\", \"text\": \"Complete the \"},\n {\"type\": \"text\", \"text\": \"onboarding proposal\", \"marks\": [{\"type\": \"bold\"}]},\n {\"type\": \"text\", \"text\": \" before Friday.\"}\n ]\n },\n {\n \"type\": \"taskList\",\n \"content\": [\n {\n \"type\": \"taskItem\",\n \"attrs\": {\"checked\": false},\n \"content\": [{\"type\": \"paragraph\", \"content\": [{\"type\": \"text\", \"text\": \"Review requirements\"}]}]\n },\n {\n \"type\": \"taskItem\",\n \"attrs\": {\"checked\": false},\n \"content\": [{\"type\": \"paragraph\", \"content\": [{\"type\": \"text\", \"text\": \"Draft document\"}]}]\n }\n ]\n },\n {\n \"type\": \"bulletList\",\n \"content\": [\n {\n \"type\": \"listItem\",\n \"content\": [{\"type\": \"paragraph\", \"content\": [{\"type\": \"text\", \"text\": \"Keep it concise\"}]}]\n }\n ]\n }\n ]\n}\n```\n\n### Priority\n\n| Value | Label |\n|-------|-------|\n| `null` | No priority |\n| `1` | Low |\n| `2` | Medium |\n| `3` | High |\n| `4` | Urgent |\n\n### Linking records\n\nTasks can be linked to multiple companies, contacts, and deals simultaneously via `companyIds`, `contactIds`, and `dealIds`.\n\n> **⚠️ Important:** When updating array fields via `PATCH`, the entire array is **replaced** — not merged. Always include all desired IDs when patching these fields.\n","operationId":"createTask","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"200":{"description":"Task created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"},"sideEffects":{"type":"array","items":{}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Get a task > Retrieve a single task by ID.\ > \ > If the task does not exist, the API returns HTTP 200 with an empty body (\`{}\`).
```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.5.0"},"tags":[{"name":"Tasks","description":"Manage tasks. Tasks can be assigned to users and linked to companies, contacts, and deals."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Create an API key from [Workspace Settings → API keys](https://app.zero.inc/settings/workspace/api)."}},"schemas":{"Task":{"type":"object","description":"A task that can be assigned to users and linked to companies, contacts, and deals.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Title of the task"},"done":{"type":"boolean","description":"Whether the task has been completed","default":false},"priority":{"type":"integer","nullable":true,"description":"Task priority level.\n- `null` — No priority\n- `1` — Low\n- `2` — Medium\n- `3` — High\n- `4` — Urgent\n","enum":[null,1,2,3,4]},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Due date and time (ISO 8601)"},"content":{"type":"object","description":"Task title as a Tiptap document. Auto-generated from `name` if not provided on creation."},"description":{"type":"object","description":"Extended notes or context for the task, in Tiptap document format. Supports rich formatting."},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Companies linked to this task"},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Contacts linked to this task"},"dealIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Deals linked to this task"},"assignedToIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"User IDs this task is assigned to"},"type":{"type":"string","nullable":true,"description":"Set automatically by integrations (e.g. `circleback` for meeting-generated tasks, `ai-generated` for AI-created tasks). Not intended to be set manually via the API.\n"},"message":{"type":"string","nullable":true},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdById":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"source":{"type":"string","nullable":true}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/tasks/{taskId}":{"get":{"tags":["Tasks"],"summary":"Get a task","description":"Retrieve a single task by ID.\n\nIf the task does not exist, the API returns HTTP 200 with an empty body (`{}`).\n","operationId":"getTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Delete a task > Delete a task. Use \`archive=true\` for soft delete (recoverable), or omit for permanent deletion. ```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.5.0"},"tags":[{"name":"Tasks","description":"Manage tasks. Tasks can be assigned to users and linked to companies, contacts, and deals."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Create an API key from [Workspace Settings → API keys](https://app.zero.inc/settings/workspace/api)."}},"schemas":{"Task":{"type":"object","description":"A task that can be assigned to users and linked to companies, contacts, and deals.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Title of the task"},"done":{"type":"boolean","description":"Whether the task has been completed","default":false},"priority":{"type":"integer","nullable":true,"description":"Task priority level.\n- `null` — No priority\n- `1` — Low\n- `2` — Medium\n- `3` — High\n- `4` — Urgent\n","enum":[null,1,2,3,4]},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"Due date and time (ISO 8601)"},"content":{"type":"object","description":"Task title as a Tiptap document. Auto-generated from `name` if not provided on creation."},"description":{"type":"object","description":"Extended notes or context for the task, in Tiptap document format. Supports rich formatting."},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Companies linked to this task"},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Contacts linked to this task"},"dealIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Deals linked to this task"},"assignedToIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"User IDs this task is assigned to"},"type":{"type":"string","nullable":true,"description":"Set automatically by integrations (e.g. `circleback` for meeting-generated tasks, `ai-generated` for AI-created tasks). Not intended to be set manually via the API.\n"},"message":{"type":"string","nullable":true},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdById":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true},"source":{"type":"string","nullable":true}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/tasks/{taskId}":{"delete":{"tags":["Tasks"],"summary":"Delete a task","description":"Delete a task. Use `archive=true` for soft delete (recoverable), or omit for permanent deletion.","operationId":"deleteTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"archive","in":"query","description":"If true, soft deletes (archives) the task instead of permanently deleting it.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"Hard delete (`archive` omitted or `false`): returns `1` on success.\nSoft delete (`archive=true`): returns a single-element array containing the archived task object.\n","oneOf":[{"type":"integer"},{"type":"array","items":{"$ref":"#/components/schemas/Task"}}]},"sideEffects":{"type":"array","items":{}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Update a task > Update an existing task.\ > \ > \> \*\*Note:\*\* The response only returns the fields that were changed — not the full task object.\ > \ > \> \*\*⚠️ Important:\*\* Array fields (\`contactIds\`, \`companyIds\`, \`dealIds\`, \`assignedToIds\`) are \*\*replaced\*\* on PATCH, not merged. Always include all desired IDs.\ > \ > To mark a task as complete: \`{"done": true}\`
```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.5.0"},"tags":[{"name":"Tasks","description":"Manage tasks. Tasks can be assigned to users and linked to companies, contacts, and deals."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Create an API key from [Workspace Settings → API keys](https://app.zero.inc/settings/workspace/api)."}},"schemas":{"TaskUpdate":{"type":"object","description":"All fields are optional. Array fields (`contactIds`, `companyIds`, `dealIds`, `assignedToIds`) replace the existing array entirely on update.\n","properties":{"name":{"type":"string"},"content":{"type":"object","description":"Replaces the entire task content. Must be a valid Tiptap document."},"description":{"type":"object","description":"Replaces the entire description. Must be a valid Tiptap document."},"done":{"type":"boolean"},"priority":{"type":"integer","nullable":true,"enum":[null,1,2,3,4]},"deadline":{"type":"string","format":"date-time","nullable":true},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"}},"contactIds":{"type":"array","items":{"type":"string","format":"uuid"}},"dealIds":{"type":"array","items":{"type":"string","format":"uuid"}},"assignedToIds":{"type":"array","items":{"type":"string","format":"uuid"}},"externalId":{"type":"string"},"source":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/tasks/{taskId}":{"patch":{"tags":["Tasks"],"summary":"Update a task","description":"Update an existing task.\n\n> **Note:** The response only returns the fields that were changed — not the full task object.\n\n> **⚠️ Important:** Array fields (`contactIds`, `companyIds`, `dealIds`, `assignedToIds`) are **replaced** on PATCH, not merged. Always include all desired IDs.\n\nTo mark a task as complete: `{\"done\": true}`\n","operationId":"updateTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"responses":{"200":{"description":"Task updated successfully. Only the fields that were changed are returned in `data`.\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Partial task object containing only the updated fields plus `updatedAt` and `updatedById`."},"sideEffects":{"type":"array","items":{}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zero.inc/features/api/tasks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.