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
changewith 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) |