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

# Create Task

> Creates a new task under a project.

### Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

### Body

<ParamField body="project_id" type="string" required>
  UUID of the project this task belongs to. Must belong to your account.
</ParamField>

<ParamField body="name" type="string" required>
  Task name.
</ParamField>

<ParamField body="description" type="string">
  Optional task description.
</ParamField>

<ParamField body="status" type="string">
  Initial status. One of: `todo` (default), `in_progress`, `done`.
</ParamField>

<ParamField body="estimated_hours" type="number">
  Estimated hours to complete the task.
</ParamField>

<ParamField body="billable" type="boolean">
  Whether this task is billable. Defaults to `false`.
</ParamField>

<ParamField body="rate" type="number">
  Hourly rate for this task. Overrides the project rate when set.
</ParamField>

<ParamField body="phase_id" type="string">
  UUID of a project phase to assign this task to. The phase must belong to the same project.
</ParamField>

### Response

<ResponseField name="success" type="boolean">`true` on creation.</ResponseField>
<ResponseField name="data" type="object">The newly created task, including an embedded `project` object.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://kliio.app/api/v1/tasks \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "project_id": "proj-uuid-...",
      "name": "Design homepage mockup",
      "estimated_hours": 8,
      "billable": true,
      "rate": 120
    }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch('https://kliio.app/api/v1/tasks', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      project_id: 'proj-uuid-...',
      name: 'Design homepage mockup',
      estimated_hours: 8,
      billable: true,
      rate: 120
    })
  })
  const { data } = await res.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "id": "task-uuid-...",
      "name": "Design homepage mockup",
      "description": null,
      "status": "todo",
      "estimated_hours": 8,
      "billable": true,
      "rate": 120,
      "total_seconds": 0,
      "phase_id": null,
      "project": { "id": "proj-uuid-...", "name": "Acme Rebrand" },
      "created_at": "2025-03-20T09:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Validation failed",
    "details": { "name": ["name is required"] }
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Project not found or access denied"
  }
  ```
</ResponseExample>