> ## 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. # Create Task > Creates a task — standalone (type: todo, default) or linked to a chat, message or ticket via type and the matching id. ## OpenAPI ````yaml api-reference/openapi-generated.json POST /v1/tasks/create 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/create: post: tags: - Tasks summary: Create a task description: >- Creates a task — standalone (type: todo, default) or linked to a chat, message or ticket via type and the matching id. operationId: createTask requestBody: content: application/json: schema: type: object properties: title: type: string minLength: 1 maxLength: 500 description: Title of the task, up to 500 characters example: Call back the customer about the renewal quote type: type: string nullable: true enum: - todo - chat - message - ticket - null description: >- Kind of task: 'todo' for a standalone task (the default when omitted or null), or 'chat', 'message' or 'ticket' for a task linked to that object. Determines which id association must carry. Immutable after creation. example: message association: type: object nullable: true properties: chat_id: type: string description: >- Chat to link the task to — required (as the only key) when type is 'chat'. For group chats, the chat_id ending with @g.us; for 1-1 chats, country code + number of the contact, with or without the @c.us suffix. The chat must exist in the workspace. example: 120363000000000000@g.us message_id: type: string description: >- Message to link the task to — required (as the only key) when type is 'message'. Accepts the message_id (true_/false_-prefixed) or the unique_id of the message. The message must exist in the workspace. example: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA ticket_id: type: string description: >- Ticket to link the task to — required (as the only key) when type is 'ticket'. The ticket must exist in the workspace and not be deleted. example: ACM-042 description: >- Links the task to its parent object. Required when type is 'chat', 'message' or 'ticket' and must then contain exactly one key — the one matching the type (association.chat_id, association.message_id or association.ticket_id). Must be omitted for todo tasks. Immutable after creation. example: message_id: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA status: type: string nullable: true enum: - open - inprogress - closed - null description: >- Initial status of the task: 'open', 'inprogress' or 'closed'. Defaults to 'open' when omitted or null. Creating a task as 'closed' records completed_metadata with the completion time and actor. example: open priority: type: integer nullable: true minimum: 1 maximum: 3 description: >- Priority of the task: 1 (low), 2 (medium) or 3 (high). Accepts a number or a numeric string. Defaults to 1 when omitted or null. example: 2 assignee: type: string nullable: true description: >- Email of the workspace member to assign the task to. Must match an existing member of the workspace, otherwise the request is rejected. Defaults to unassigned. example: user@example.com due_date: type: string nullable: true description: >- When the task is due, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Defaults to no due date. example: '2026-01-20T17:00:00Z' notes: type: string nullable: true description: Free-form notes to store on the task example: Customer prefers a call after 3pm IST remind_at: type: string nullable: true description: >- When to fire a reminder for the task, as an ISO 8601 timestamp (other common date formats are accepted and normalized to UTC ISO 8601). Defaults to no reminder. example: '2026-01-20T09:00:00Z' created_by: type: string nullable: true description: >- Email of the workspace member to record as the creator (also recorded as last_updated_by). Must match an existing member of the workspace. Defaults to "api". example: user@example.com required: - title responses: '200': description: The created 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: >- The chat, message or ticket referenced in association does not exist in the workspace content: application/json: examples: error: summary: >- The chat, message or ticket referenced in association does not exist in the workspace value: code: NOT_FOUND_ERROR message: >- The chat, message or ticket referenced in association does not exist in the workspace status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: >- The chat, message or ticket referenced in association does not exist in the workspace status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: >- The chat, message or ticket referenced in association does not exist in the workspace 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.createTask({ title: 'Call back the customer about the renewal quote', }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X POST 'https://api.periskope.app/v1/tasks/create' \ -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.