---
title: "Create a task"
method: POST
path: "/api/tasks"
---

# Create a task

`POST /api/tasks`

## Request

- Base URL: `https://taskhold.com`
- URL: `https://taskhold.com/api/tasks`
- Auth: HTTP bearer

Creates a task. With an API key it is recorded as created by an agent.

## Request body

- TaskCreate
  - `title` string, required: Short task title
  - `description` string: Details
  - `project_id` string, uuid, nullable: Project; omit for none
  - `priority` 'low' | 'medium' | 'high' | 'urgent': Priority
  - `status` 'todo' | 'in_progress' | 'blocked' | 'done': Initial status
  - `labels` string[]: Label names; created if missing
  - `code_file_path` string: File a TODO came from
  - `code_line_number` integer: Line of that TODO

## Response `201`

Created

- object
  - `task` Task
    - `id` string, uuid
    - `title` string
    - `description` string, nullable
    - `status` 'todo' | 'in_progress' | 'blocked' | 'done'
    - `priority` 'low' | 'medium' | 'high' | 'urgent'
    - `project_id` string, uuid, nullable
    - `blocked_reason` string, nullable
    - `completed_summary` string, nullable
    - `created_by` 'human' | 'agent'
    - `code_file_path` string, nullable
    - `code_line_number` integer, nullable
    - `labels` Label[]
      - `id` string, uuid
      - `name` string
      - `color` string
    - `notes` Note[]
      - `id` string, uuid
      - `task_id` string, uuid
      - `content` string
      - `created_by` 'human' | 'agent'
      - `created_at` string, date-time
    - `completed_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400`: Validation failed (details in the body)
- `401`: Missing, malformed or unknown API key. `reason` is one of missing_key, bad_header, not_a_taskhold_key, unknown_key; `message` says what to do and `url` links to Settings.
- `402`: The key is valid but the account has no active subscription. `url` links to Billing.
- `403`: Fair-use task ceiling reached
- `404`: project_id not found
- `500`: Server error

---

[API](https://skmtc.dev/taskhold/apis/taskhold-api.md) · [All operations](https://skmtc.dev/taskhold/apis/taskhold-api/llms.txt) · [OpenAPI document](https://skmtc.dev/taskhold/apis/taskhold-api/revisions/496ae75d7cdd?raw)