> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a task

> Create work in your workspace with a title, schedule, owners, and linked records.

Requires `tasks:write` and current workspace membership. A successful request
returns `201` with the created task under `data`.

<ParamField body="title" type="string" required>
  Task title, from 1 to 500 characters.
</ParamField>

<ParamField body="description" type="string">
  Task description, up to 100,000 characters.
</ParamField>

<ParamField body="status" type="string">
  A task-status slug defined in the workspace.
</ParamField>

<ParamField body="priority" type="enum<string>" enum={["no_priority", "low", "medium", "high", "urgent"]}>
  Priority for the task.
</ParamField>

<ParamField body="start_date" type="number">
  Start time as a Unix timestamp in milliseconds.
</ParamField>

<ParamField body="due_date" type="number">
  Due time as a Unix timestamp in milliseconds. When both dates are supplied,
  the start must not be later than the due date.
</ParamField>

<ParamField body="parent_task_id" type="string">
  An existing parent task accessible to the key's owner.
</ParamField>

<ParamField body="assignees" type="string[]">
  Up to 50 workspace auth-user IDs.
</ParamField>

<ParamField body="estimated_time" type="integer">
  Estimated effort in minutes; a positive integer.
</ParamField>

<ParamField body="linked_record_ids" type="string[]">
  Up to 10 record IDs to link at creation. This field is not accepted by the
  task update endpoint.
</ParamField>

Optional fields can be omitted for a minimal task. Use real status slugs and
auth-user IDs from Kato; the general public API does not expose a member
directory or task-status list endpoint.

<ResponseField name="data" type="object">
  The created task, including its `id`. Response dates use ISO 8601, and some
  response names differ from write inputs: `dueDate` and `estimatedTime`.
  See the [full response conventions](/api-reference/tasks/overview#date-and-response-formats).
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl --fail-with-body --silent --show-error \
    https://api.getkato.io/v1/tasks \
    -H "Authorization: Bearer $KATO_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
      "title": "Prepare the Northlane kickoff",
      "description": "Confirm the agenda and collect open questions.",
      "priority": "high",
      "estimated_time": 45
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "task_example",
      "title": "Prepare the Northlane kickoff",
      "description": "Confirm the agenda and collect open questions.",
      "status": "todo",
      "priority": "high",
      "assignees": [],
      "start_date": null,
      "dueDate": null,
      "parent_task_id": null,
      "timeLogged": 0,
      "estimatedTime": 45,
      "archived": false,
      "createdBy": "user_example",
      "createdAt": "2026-09-07T12:00:00.000Z",
      "updatedAt": "2026-09-07T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

The response example uses illustrative IDs and a workspace with a `todo` default
status. Your workspace's status configuration determines the returned slug.

Task creation uses the same service as the app, including activity,
notifications, workflow triggers, and integration behavior. A timeout can occur
after a successful write; check the workspace before retrying a creation request.


## Related topics

- [Tasks API](/api-reference/tasks/overview.md)
- [Create a Raycast task](/api-reference/raycast/tasks-create.md)
- [Organize tasks](/documentation/organize-tasks.md)
- [All endpoints](/api-reference/endpoints.md)
- [Plan a project from a brief](/recipes/project-from-brief.md)