> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/tasks.md).

# Tasks

To-dos for the office.

A task is a to-do for the office, with a deadline and an assignee, often about a customer, lead, or estimate.

Fields: [The task object](https://docs.shortcutco.com/developers/reference/objects/task).

## List a customer's tasks

> Tasks for the customer, including tasks from when they were a lead, newest first. The same tasks as \`GET /v1/tasks?customerId=\`.\
> \
> Returns a list of \[task objects]\(<https://docs.shortcutco.com/developers/reference/objects/task>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Tasks","description":"A task is a to-do for the office, with a deadline and an assignee, often about a customer, lead, or estimate.\n\nFields: [The task object](https://docs.shortcutco.com/developers/reference/objects/task)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["customers:read","tasks:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The task's id."},"object":{"type":"string","const":"task","description":"Always `task`."},"name":{"type":"string","description":"What to do."},"description":{"type":["string","null"],"description":"More detail, when there is any."},"status":{"type":"string","enum":["pending","complete"],"description":"Whether the task is done."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it is due, ISO 8601 in UTC."},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was completed."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/PersonReference"},{"type":"null"}],"description":"Who it is assigned to; null when unassigned."},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer it is for."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead it is for."},"estimateId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The estimate it is for."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer's property the task is about: the one it was tagged with, else its estimate's property; null when it is about the whole account."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","description","status","deadline","completedAt","assignee","customerId","leadId","estimateId","propertyId","createdAt","updatedAt"],"additionalProperties":false,"description":"A to-do for the office, often about a customer, lead, or estimate."},"PersonReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The staff member's id (`GET /v1/users/{id}`)."},"name":{"type":["string","null"],"description":"Their name."}},"required":["id","name"],"additionalProperties":false,"description":"A staff member, by id and name."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/customers/{id}/tasks":{"get":{"operationId":"customers.tasks.list","tags":["Tasks"],"summary":"List a customer's tasks","description":"Tasks for the customer, including tasks from when they were a lead, newest first. The same tasks as `GET /v1/tasks?customerId=`.\n\nReturns a list of [task objects](https://docs.shortcutco.com/developers/reference/objects/task).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"status","in":"query","required":false,"description":"Only tasks with this status.","schema":{"type":"string","enum":["pending","complete"]}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## List tasks

> The workspace's tasks, newest first. Filter by status, assignee, customer, or lead.\
> \
> Returns a list of \[task objects]\(<https://docs.shortcutco.com/developers/reference/objects/task>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Tasks","description":"A task is a to-do for the office, with a deadline and an assignee, often about a customer, lead, or estimate.\n\nFields: [The task object](https://docs.shortcutco.com/developers/reference/objects/task)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["tasks:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The task's id."},"object":{"type":"string","const":"task","description":"Always `task`."},"name":{"type":"string","description":"What to do."},"description":{"type":["string","null"],"description":"More detail, when there is any."},"status":{"type":"string","enum":["pending","complete"],"description":"Whether the task is done."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it is due, ISO 8601 in UTC."},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was completed."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/PersonReference"},{"type":"null"}],"description":"Who it is assigned to; null when unassigned."},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer it is for."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead it is for."},"estimateId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The estimate it is for."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer's property the task is about: the one it was tagged with, else its estimate's property; null when it is about the whole account."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","description","status","deadline","completedAt","assignee","customerId","leadId","estimateId","propertyId","createdAt","updatedAt"],"additionalProperties":false,"description":"A to-do for the office, often about a customer, lead, or estimate."},"PersonReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The staff member's id (`GET /v1/users/{id}`)."},"name":{"type":["string","null"],"description":"Their name."}},"required":["id","name"],"additionalProperties":false,"description":"A staff member, by id and name."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tasks":{"get":{"operationId":"tasks.list","tags":["Tasks"],"summary":"List tasks","description":"The workspace's tasks, newest first. Filter by status, assignee, customer, or lead.\n\nReturns a list of [task objects](https://docs.shortcutco.com/developers/reference/objects/task).","parameters":[{"name":"limit","in":"query","required":false,"description":"How many items to return, 1-200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `meta.nextCursor` from the previous page. Omit it for the first page.","schema":{"type":"string","minLength":1,"maxLength":4096}},{"name":"status","in":"query","required":false,"description":"Only tasks with this status.","schema":{"type":"string","enum":["pending","complete"]}},{"name":"assigneeId","in":"query","required":false,"description":"Only tasks assigned to this staff member.","schema":{"type":"string","format":"uuid"}},{"name":"customerId","in":"query","required":false,"description":"Only tasks for this customer, including tasks from when they were a lead.","schema":{"type":"string","format":"uuid"}},{"name":"leadId","in":"query","required":false,"description":"Only tasks for this lead.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"meta":{"type":"object","properties":{"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"hasMore":{"type":"boolean","description":"Whether another page exists."}},"required":["nextCursor","hasMore"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Create a task

> Creates a to-do for the office, optionally about a customer or lead, with a deadline and an assignee. It shows on the customer's timeline and in the assignee's tasks. Your Automations rules on new tasks run only when the token has \`automations:trigger\`. Send an \`Idempotency-Key\` to retry safely.\
> \
> Returns \[the task object]\(<https://docs.shortcutco.com/developers/reference/objects/task>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Tasks","description":"A task is a to-do for the office, with a deadline and an assignee, often about a customer, lead, or estimate.\n\nFields: [The task object](https://docs.shortcutco.com/developers/reference/objects/task)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["tasks:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any string up to 255 characters. Retrying with the same key returns the first response instead of repeating the write, for 24 hours.","schema":{"type":"string","maxLength":255}}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The task's id."},"object":{"type":"string","const":"task","description":"Always `task`."},"name":{"type":"string","description":"What to do."},"description":{"type":["string","null"],"description":"More detail, when there is any."},"status":{"type":"string","enum":["pending","complete"],"description":"Whether the task is done."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it is due, ISO 8601 in UTC."},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was completed."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/PersonReference"},{"type":"null"}],"description":"Who it is assigned to; null when unassigned."},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer it is for."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead it is for."},"estimateId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The estimate it is for."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer's property the task is about: the one it was tagged with, else its estimate's property; null when it is about the whole account."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","description","status","deadline","completedAt","assignee","customerId","leadId","estimateId","propertyId","createdAt","updatedAt"],"additionalProperties":false,"description":"A to-do for the office, often about a customer, lead, or estimate."},"PersonReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The staff member's id (`GET /v1/users/{id}`)."},"name":{"type":["string","null"],"description":"Their name."}},"required":["id","name"],"additionalProperties":false,"description":"A staff member, by id and name."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tasks":{"post":{"operationId":"tasks.add","tags":["Tasks"],"summary":"Create a task","description":"Creates a to-do for the office, optionally about a customer or lead, with a deadline and an assignee. It shows on the customer's timeline and in the assignee's tasks. Your Automations rules on new tasks run only when the token has `automations:trigger`. Send an `Idempotency-Key` to retry safely.\n\nReturns [the task object](https://docs.shortcutco.com/developers/reference/objects/task).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"What to do, up to 200 characters."},"description":{"type":"string","maxLength":4000,"description":"More detail."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}],"description":"When it is due: a date (`YYYY-MM-DD`) or an ISO 8601 time."},"assigneeId":{"type":"string","format":"uuid","description":"The staff member to assign it to (`GET /v1/users`)."},"customerId":{"type":"string","format":"uuid","description":"The customer it is about."},"leadId":{"type":"string","format":"uuid","description":"The lead it is about. Send at most one of `customerId` and `leadId`."},"propertyId":{"type":"string","format":"uuid","description":"The customer's property it is about (`GET /v1/customers/{id}/properties`), or the lead's property. Needs `customerId` or `leadId`; leave out for the whole account."}},"required":["name"],"additionalProperties":false,"description":"A new task."}}}},"responses":{"201":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get a task

> One task.\
> \
> Returns \[the task object]\(<https://docs.shortcutco.com/developers/reference/objects/task>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Tasks","description":"A task is a to-do for the office, with a deadline and an assignee, often about a customer, lead, or estimate.\n\nFields: [The task object](https://docs.shortcutco.com/developers/reference/objects/task)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["tasks:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The task's id."},"object":{"type":"string","const":"task","description":"Always `task`."},"name":{"type":"string","description":"What to do."},"description":{"type":["string","null"],"description":"More detail, when there is any."},"status":{"type":"string","enum":["pending","complete"],"description":"Whether the task is done."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it is due, ISO 8601 in UTC."},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was completed."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/PersonReference"},{"type":"null"}],"description":"Who it is assigned to; null when unassigned."},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer it is for."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead it is for."},"estimateId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The estimate it is for."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer's property the task is about: the one it was tagged with, else its estimate's property; null when it is about the whole account."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","description","status","deadline","completedAt","assignee","customerId","leadId","estimateId","propertyId","createdAt","updatedAt"],"additionalProperties":false,"description":"A to-do for the office, often about a customer, lead, or estimate."},"PersonReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The staff member's id (`GET /v1/users/{id}`)."},"name":{"type":["string","null"],"description":"Their name."}},"required":["id","name"],"additionalProperties":false,"description":"A staff member, by id and name."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tasks/{id}":{"get":{"operationId":"tasks.get","tags":["Tasks"],"summary":"Get a task","description":"One task.\n\nReturns [the task object](https://docs.shortcutco.com/developers/reference/objects/task).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Update a task

> Changes a task's name, description, deadline, or assignee, or completes or reopens it with \`status\`. Completing records who completed it and when, as the app does.\
> \
> Returns \[the task object]\(<https://docs.shortcutco.com/developers/reference/objects/task>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Tasks","description":"A task is a to-do for the office, with a deadline and an assignee, often about a customer, lead, or estimate.\n\nFields: [The task object](https://docs.shortcutco.com/developers/reference/objects/task)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":["tasks:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The task's id."},"object":{"type":"string","const":"task","description":"Always `task`."},"name":{"type":"string","description":"What to do."},"description":{"type":["string","null"],"description":"More detail, when there is any."},"status":{"type":"string","enum":["pending","complete"],"description":"Whether the task is done."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it is due, ISO 8601 in UTC."},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was completed."},"assignee":{"anyOf":[{"$ref":"#/components/schemas/PersonReference"},{"type":"null"}],"description":"Who it is assigned to; null when unassigned."},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer it is for."},"leadId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The lead it is for."},"estimateId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The estimate it is for."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The customer's property the task is about: the one it was tagged with, else its estimate's property; null when it is about the whole account."},"createdAt":{"type":"string","format":"date-time","description":"When it was created, ISO 8601 in UTC."},"updatedAt":{"type":"string","format":"date-time","description":"When it last changed, ISO 8601 in UTC."}},"required":["id","object","name","description","status","deadline","completedAt","assignee","customerId","leadId","estimateId","propertyId","createdAt","updatedAt"],"additionalProperties":false,"description":"A to-do for the office, often about a customer, lead, or estimate."},"PersonReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The staff member's id (`GET /v1/users/{id}`)."},"name":{"type":["string","null"],"description":"Their name."}},"required":["id","name"],"additionalProperties":false,"description":"A staff member, by id and name."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflict with the current state or an in-flight request with the same idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request cannot be applied, or its idempotency key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tasks/{id}":{"patch":{"operationId":"tasks.update","tags":["Tasks"],"summary":"Update a task","description":"Changes a task's name, description, deadline, or assignee, or completes or reopens it with `status`. Completing records who completed it and when, as the app does.\n\nReturns [the task object](https://docs.shortcutco.com/developers/reference/objects/task).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"What to do."},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"description":"More detail; null clears it."},"deadline":{"anyOf":[{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]},{"type":"null"}],"description":"When it is due; null clears it."},"assigneeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Who it is assigned to; null unassigns it."},"status":{"type":"string","enum":["pending","complete"],"description":"`complete` to complete it, `pending` to reopen it."},"propertyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Move it to one of its customer's properties; null makes it about the whole account."}},"additionalProperties":false,"description":"The fields to change; send at least one."}}}},"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```
