> ## 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.

# The Task Object

> The Task object represents a task on Periskope.

<ResponseExample>
  ```json The Task Object theme={null}
    {
        "task_id": "task-elnizmojzrjsogdm",
        "title": "Resolve customer escalation",
        "type": "message",
        "status": "closed",
        "priority": 3,
        "assignee": "ankit.singh@hashlabs.dev",
        "created_by": "anjali.pandey@hashlabs.dev",
        "last_updated_by": "ankit.singh@hashlabs.dev",
        "created_at": "2026-06-03T06:00:56.592+00:00",
        "last_updated_at": "2026-06-04T18:09:36.420636+00:00",
        "due_date": "2026-06-15T18:00:00+00:00",
        "remind_at": "2026-06-18T18:00:00+00:00",
        "notes": "Customer escalated via email — coordinate with support",
        "chat_id": "919205202401@c.us",
        "association": {
            "type": "message",
            "message_id": "true_4ca42ab6-77a9-428d-b614-5eb37bcf8f95_anjali.pandey@hashlabs.dev",
            "chat_id": "919205202401@c.us"
        },
        "completed_metadata": {
            "completed_at": "2026-06-04T18:09:36.407Z",
            "completed_by": "ankit.singh@hashlabs.dev"
        }
    }
  ```
</ResponseExample>

A Task always has the same set of fields. The `association` field varies depending on `type`. The four examples below cover every possible shape.

## Example: todo task

A standalone to-do has no association. The `chat_id` field and `association` are both `null`.

```json theme={null}
{
  "task_id": "task-00000000000000a1",
  "title": "Example todo task title",
  "type": "todo",
  "status": "closed",
  "priority": 1,
  "assignee": "member1@example.com",
  "created_by": "admin@example.com",
  "last_updated_by": "admin@example.com",
  "created_at": "2026-01-01T10:00:00.000Z",
  "last_updated_at": "2026-01-02T15:30:00.000Z",
  "due_date": "2026-01-05T17:00:00.000Z",
  "remind_at": "2026-01-05T16:30:00.000Z",
  "notes": "Example notes for a todo task.",
  "chat_id": null,
  "association": null,
  "completed_metadata": {
    "completed_at": "2026-01-02T15:30:00.000Z",
    "completed_by": "admin@example.com"
  }
}
```

## Example: chat task

Linked to a chat. `association.chat_id` and the top-level `chat_id` mirror each other.

```json theme={null}
{
  "task_id": "task-00000000000000b2",
  "title": "Example chat task title",
  "type": "chat",
  "status": "closed",
  "priority": 2,
  "assignee": "member2@example.com",
  "created_by": "member1@example.com",
  "last_updated_by": "member2@example.com",
  "created_at": "2026-02-01T09:00:00.000Z",
  "last_updated_at": "2026-02-03T11:45:00.000Z",
  "due_date": "2026-02-10T17:00:00.000Z",
  "remind_at": "2026-02-10T16:30:00.000Z",
  "notes": "Example notes for a chat task.",
  "chat_id": "911234567890",
  "association": {
    "type": "chat",
    "chat_id": "911234567890"
  },
  "completed_metadata": {
    "completed_at": "2026-02-03T11:45:00.000Z",
    "completed_by": "member2@example.com"
  }
}
```

## Example: message task

Linked to a specific message inside a chat. `association.chat_id` is the chat the message belongs to (denormalized for convenience).

```json theme={null}
{
  "task_id": "task-00000000000000c3",
  "title": "Example message task title",
  "type": "message",
  "status": "closed",
  "priority": 3,
  "assignee": "member3@example.com",
  "created_by": "member1@example.com",
  "last_updated_by": "member3@example.com",
  "created_at": "2026-03-01T08:00:00.000Z",
  "last_updated_at": "2026-03-04T12:00:00.000Z",
  "due_date": "2026-03-10T17:00:00.000Z",
  "remind_at": "2026-03-10T16:00:00.000Z",
  "notes": "Example notes for a message task.",
  "chat_id": "911234567890",
  "association": {
    "type": "message",
    "message_id": "msg-0000000000000001",
    "chat_id": "911234567890"
  },
  "completed_metadata": {
    "completed_at": "2026-03-04T12:00:00.000Z",
    "completed_by": "member3@example.com"
  }
}
```

## Example: ticket task

Linked to a ticket. `association.chat_id` is the chat the ticket lives in.

```json theme={null}
{
  "task_id": "task-00000000000000d4",
  "title": "Example ticket task title",
  "type": "ticket",
  "status": "closed",
  "priority": 1,
  "assignee": "member4@example.com",
  "created_by": "member2@example.com",
  "last_updated_by": "member4@example.com",
  "created_at": "2026-04-01T07:00:00.000Z",
  "last_updated_at": "2026-04-05T13:15:00.000Z",
  "due_date": "2026-04-15T17:00:00.000Z",
  "remind_at": "2026-04-15T16:00:00.000Z",
  "notes": "Example notes for a ticket task.",
  "chat_id": "911234567890",
  "association": {
    "type": "ticket",
    "ticket_id": "tkt-0000000000000001",
    "chat_id": "911234567890"
  },
  "completed_metadata": {
    "completed_at": "2026-04-05T13:15:00.000Z",
    "completed_by": "member4@example.com"
  }
}
```

## Attributes

<ParamField path="task_id" type="string">
  Server-generated. Stable identifier for the task (e.g. `task-00000000000000a1`).
</ParamField>

<ParamField path="title" type="string">
  Human-readable summary. 1–500 characters.
</ParamField>

<ParamField path="type" type="string">
  What this task is attached to. One of `todo`, `chat`, `message`, `ticket`. Defaults to `todo`. Immutable after creation.
</ParamField>

<ParamField path="status" type="string">
  Workflow state. One of `open`, `inprogress`, `closed`. Defaults to `open`.
</ParamField>

<ParamField path="priority" type="number">
  Numeric priority. One of `1`, `2`, `3`. `1` is the highest. Defaults to `1`.
</ParamField>

<ParamField path="assignee" type="string | null">
  Email of an org member, or `null` if unassigned.
</ParamField>

<ParamField path="created_by" type="string">
  Email of the org member who created the task, or the literal string `"api"` if not specified on create. Immutable after creation.
</ParamField>

<ParamField path="last_updated_by" type="string | null">
  Email of whoever last modified the task, or `"api"`.
</ParamField>

<ParamField path="created_at" type="string">
  ISO 8601 formatted timestamp when the task was created. Immutable.
</ParamField>

<ParamField path="last_updated_at" type="string">
  ISO 8601 formatted timestamp. Auto-updated on every PATCH.
</ParamField>

<ParamField path="due_date" type="string | null">
  ISO 8601 timestamp for when the task is due. `null` if no deadline.
</ParamField>

<ParamField path="remind_at" type="string | null">
  ISO 8601 timestamp for when a reminder should fire. `null` if no reminder.
</ParamField>

<ParamField path="notes" type="string | null">
  Free-form additional context.
</ParamField>

<ParamField path="chat_id" type="string | null">
  Derived from the `association` at create time. Populated for `chat`, `message`, and `ticket` tasks; `null` for `todo`.
</ParamField>

<ParamField path="association" type="object | null">
  Structured reference to the linked resource. `null` for `todo` tasks. Immutable after creation.

  <Expandable>
    <ParamField path="type" type="string">
      Matches the task `type`. One of `chat`, `message`, `ticket`.
    </ParamField>

    <ParamField path="chat_id" type="string">
      The chat the linked resource belongs to. Always present for non-todo associations.
    </ParamField>

    <ParamField path="message_id" type="string">
      Present only when `type` is `message`.
    </ParamField>

    <ParamField path="ticket_id" type="string">
      Present only when `type` is `ticket`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="completed_metadata" type="object | null">
  Auto-managed completion record. Populated when the task is closed.

  <Expandable>
    <ParamField path="completed_at" type="string">
      ISO 8601 timestamp when the task was closed.
    </ParamField>

    <ParamField path="completed_by" type="string">
      Email of the org member who closed the task, or `"api"`.
    </ParamField>
  </Expandable>
</ParamField>