> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Update Task > Updates a task — any combination of title, status, priority, assignee, due_date, notes and remind_at; at least one required. The type and associations cannot change. ## OpenAPI ````yaml api-reference/openapi-generated.json PATCH /v1/tasks/{task_id} openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/tasks/{task_id}: patch: tags: - Tasks summary: Update a task description: >- Updates a task — any combination of title, status, priority, assignee, due_date, notes and remind_at; at least one required. The type and associations cannot change. operationId: updateTask parameters: - schema: type: string minLength: 1 description: >- Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created example: task-aaaaaaaaaaaa required: true description: >- Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created name: task_id in: path requestBody: content: application/json: schema: type: object properties: title: type: string minLength: 1 maxLength: 500 description: >- New title of the task, up to 500 characters. Cannot be null or empty. example: Call back the customer about the renewal quote status: type: string nullable: true enum: - open - inprogress - closed - null description: >- New status of the task: 'open', 'inprogress' or 'closed'. Pass null or an empty string to reset it to 'open'. Moving the task to 'closed' records completed_metadata with the completion time and actor; moving it out of 'closed' clears it. example: closed priority: type: integer nullable: true minimum: 1 maximum: 3 description: >- New priority of the task: 1 (low), 2 (medium) or 3 (high). Accepts a number or a numeric string. Pass null or an empty string to reset the priority to 1. example: 3 assignee: type: string nullable: true description: >- Email of the workspace member to reassign the task to. Must match an existing member of the workspace. Pass null or an empty string to unassign the task. example: user@example.com due_date: type: string nullable: true description: >- New due date, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Pass null or an empty string to clear the due date. example: '2026-01-20T17:00:00Z' notes: type: string nullable: true description: >- New notes for the task. Pass null or an empty string to clear them. example: Customer prefers a call after 3pm IST remind_at: type: string nullable: true description: >- New reminder time, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Pass null or an empty string to clear the reminder. example: '2026-01-20T09:00:00Z' last_updated_by: type: string nullable: true description: >- Email of the workspace member to record as the author of this update. Must match an existing member of the workspace. Defaults to "api". example: user@example.com responses: '200': description: The updated task content: application/json: schema: $ref: '#/components/schemas/Task' examples: default: summary: Response body value: task_id: task-aaaaaaaaaaaa title: Call back the customer about the renewal quote type: message status: open priority: 2 assignee: user@example.com created_by: api last_updated_by: api created_at: '2026-01-15T09:30:00.000Z' last_updated_at: '2026-01-15T09:30:00.000Z' due_date: '2026-01-20T17:00:00.000Z' remind_at: '2026-01-20T09:00:00.000Z' notes: Customer prefers a call after 3pm IST chat_id: 120363000000000000@g.us association: type: message chat_id: 120363000000000000@g.us message_id: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA ticket_id: ACM-042 completed_metadata: completed_at: '2026-01-21T10:15:00.000Z' completed_by: user@example.com '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '404': description: No task matches task_id content: application/json: examples: error: summary: No task matches task_id value: code: NOT_FOUND_ERROR message: No task matches task_id status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: No task matches task_id status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: No task matches task_id status: 404 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', }); async function main() { const response = await client.tasks.updateTask({ task_id: 'task-aaaaaaaaaaaa', title: 'Call back the customer about the renewal quote', }); console.log(response); } main(); - lang: bash label: cURL source: >- curl -X PATCH 'https://api.periskope.app/v1/tasks/task-aaaaaaaaaaaa' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "title": "Call back the customer about the renewal quote" }' components: schemas: Task: type: object properties: task_id: type: string description: >- Unique id of the task (task-xxxxxxxxxxxxxxxx). Use this value as the task_id path parameter when fetching or updating the task. example: task-aaaaaaaaaaaa title: type: string description: Title of the task, up to 500 characters example: Call back the customer about the renewal quote type: type: string enum: - todo - chat - message - ticket description: >- Kind of task: 'todo' for a standalone task, or 'chat', 'message' or 'ticket' for a task linked to that object. Immutable after creation. example: message status: type: string enum: - open - inprogress - closed description: 'Lifecycle status of the task: ''open'', ''inprogress'' or ''closed''' example: open priority: type: integer description: 'Priority of the task: 1 (low), 2 (medium) or 3 (high)' example: 2 assignee: type: string description: >- Email of the workspace member the task is assigned to. null when the task is unassigned. example: user@example.com created_by: type: string description: >- Who created the task: a member's email, or "api" when created via the API without a created_by example: api last_updated_by: type: string description: >- Who last changed the task: a member's email, or "api" for API changes without a last_updated_by example: api created_at: type: string description: When the task was created, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' last_updated_at: type: string description: When the task was last updated, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' due_date: type: string description: >- When the task is due, as an ISO 8601 UTC timestamp. null when no due date is set. example: '2026-01-20T17:00:00.000Z' remind_at: type: string description: >- When a reminder for the task fires, as an ISO 8601 UTC timestamp. null when no reminder is set. example: '2026-01-20T09:00:00.000Z' notes: type: string description: Free-form notes on the task. null when none were set. example: Customer prefers a call after 3pm IST chat_id: type: string description: >- Id of the chat the task is linked to (directly, or through its message or ticket). null for todo tasks. example: 120363000000000000@g.us association: $ref: '#/components/schemas/TaskAssociation' completed_metadata: type: object properties: completed_at: type: string description: When the task was closed, as an ISO 8601 timestamp example: '2026-01-21T10:15:00.000Z' completed_by: type: string description: >- Who closed the task: a member's email, or "api" for API changes without an actor example: user@example.com description: >- Completion details, recorded when the task moves to status 'closed' and cleared when it is reopened. null while the task is open or inprogress. description: >- A task in the workspace. Tasks are either standalone to-dos (type: todo) or linked to a chat, message or ticket via association. Tasks belong to the workspace as a whole, not to a specific phone. TaskAssociation: type: object properties: type: type: string enum: - chat - message - ticket description: >- Kind of object the task is linked to: 'chat', 'message' or 'ticket'. Mirrors the task's type. example: message chat_id: type: string description: >- Id of the chat the linked object belongs to — @c.us for 1-1 chats, @g.us for group chats. Present for every association kind; the chat itself for chat tasks, the chat of the message or ticket otherwise. null when the chat could not be resolved. example: 120363000000000000@g.us message_id: type: string description: >- message_id of the linked message. Present only when type is 'message'. example: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA ticket_id: type: string description: ticket_id of the linked ticket. Present only when type is 'ticket'. example: ACM-042 description: The chat, message or ticket the task is linked to. null for todo tasks. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.