# Create a task

> POST /tasks: Create a task

`POST https://usedocs.app/v1/tasks`

Starts background work that ends in drafts for review; nothing is published. Poll GET /tasks/{id} or subscribe to the `task.completed` webhook.

- **Write or update docs:** send `description` (what's needed).
- **Document a code change:** send `change` with the diff (or changed paths and commits). usedocs reads it against your docs and proposes edits to the articles it affects, new articles it needs, and a changelog entry. This is the same job a merged pull request runs on the GitHub app, so it works from any CI or code host.

Send an `Idempotency-Key` header so a retried CI job doesn't start the task twice (kept for 24 hours).

```bash
git diff origin/main...HEAD | jq -Rs '{change: {kind: "pr", title: "Add CSV export", url: "https://github.com/acme/app/pull/42", diff: .}}' | \
  curl -X POST "https://usedocs.app/v1/tasks" -H "Authorization: Bearer $USEDOCS_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $CI_COMMIT_SHA" --data-binary @-
```

## Authentication

Bearer token (`content:write`): A workspace API key: ud_live_…

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | `string` |  |  |
| `bot_id` | query | `string` |  | Only for a key that covers several bots (see GET /bots). Or send the Usedocs-Bot header. |

## Request body

Required, `application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string` |  | What should change in the docs. Required without change. |
| `title` | `string` |  |  |
| `change` | `object` |  |  |

## Responses

| Status | Description |
| --- | --- |
| `201` | The task. |
| `400` | The request is missing something or has a bad value. |
| `401` | No API key, or the key is revoked. |
| `402` | The workspace is paused; reads still work. |
| `403` | A read key on a write, or a key for another bot. |
| `404` | Not found. |
| `429` | Rate limited: 120 requests a minute per key, 30 tasks an hour. See Retry-After. |

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `type` | `string` | change, write_article, document_feature, refresh_article, replace_term, draft_gaps, check_all, audit |
| `title` | `string` |  |
| `status` | `string` | One of: `queued`, `in_progress`, `completed`, `failed`. |
| `result` | `object | null` |  |
| `error` | `string | null` |  |
| `createdAt` | `string (date-time)` |  |