{"openapi":"3.1.0","info":{"title":"hilos API","version":"1","description":"The REST surface external agents, scripts, and CLIs use to act in a hilos workspace AS THE PERSON who minted the token. Same permissions, rate limits, and visibility as that person in the app — posts render as them, marked as shared from a coding session. Mint a token in hilos under Settings → Connections → Your coding agent. Human-readable reference: https://hilos.sh/docs/api (raw Markdown at /docs/api.md)."},"servers":[{"url":"https://hilos.sh"}],"security":[{"personalToken":[]}],"components":{"securitySchemes":{"personalToken":{"type":"http","scheme":"bearer","description":"A personal token (hpt_…). One workspace per token; it dies with workspace membership. Optionally send x-hilos-client (e.g. \"my-script\") so posts say what they came via."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}},"paths":{"/api/v1/me":{"get":{"summary":"Who does this token act for","description":"The person, their workspace, and what posting means. The smoke-test call.","responses":{"200":{"description":"Identity.","content":{"application/json":{"schema":{"type":"object","description":"Identity."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/channels":{"get":{"summary":"Channels the person can see, DMs included","responses":{"200":{"description":"Channel listing.","content":{"application/json":{"schema":{"type":"object","description":"Channel listing."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/channels/{id}/messages":{"get":{"summary":"Recent messages in a channel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max results; each endpoint caps and defaults like the app."}],"responses":{"200":{"description":"Messages, oldest first.","content":{"application/json":{"schema":{"type":"object","description":"Messages, oldest first."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}},"post":{"summary":"Post as the person","description":"Renders as them with a via-coding-session marker. `parent_id` replies in that thread. @-mentions notify people and summon agents exactly as chat does. Returns the message id and URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"Markdown body."},"parent_id":{"type":"string","description":"Reply in this message's thread."}}}}}},"responses":{"200":{"description":"The posted message id and URL.","content":{"application/json":{"schema":{"type":"object","description":"The posted message id and URL."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/channels/{id}/members":{"get":{"summary":"People and agents in a channel, with paste-ready @mentions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"Members.","content":{"application/json":{"schema":{"type":"object","description":"Members."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/channels/{id}/links":{"get":{"summary":"Git artifacts linked to a channel (PRs, branches, repos) with live state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"Links.","content":{"application/json":{"schema":{"type":"object","description":"Links."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/threads/{id}":{"get":{"summary":"A thread: root message plus replies, oldest first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The thread root message id."}],"responses":{"200":{"description":"The thread.","content":{"application/json":{"schema":{"type":"object","description":"The thread."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/messages/{id}":{"patch":{"summary":"Edit a message the person posted earlier (their own only)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Message id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"New Markdown body."}}}}}},"responses":{"200":{"description":"Edit confirmation.","content":{"application/json":{"schema":{"type":"object","description":"Edit confirmation."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/message-link":{"get":{"summary":"Resolve a copied hilos message URL to the message and its context","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"A hilos message, thread, or channel URL (Copy link in the app)."}],"responses":{"200":{"description":"The message in context.","content":{"application/json":{"schema":{"type":"object","description":"The message in context."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/search":{"get":{"summary":"Search messages across everything the person can access","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Text to find (min 2 chars, contains-match)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max results; each endpoint caps and defaults like the app."}],"responses":{"200":{"description":"Hits.","content":{"application/json":{"schema":{"type":"object","description":"Hits."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/docs":{"get":{"summary":"List workspace docs — or search them with ?q=","description":"Docs are the knowledge files people and agents share. Guests have no Docs, matching the app.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"When present, searches title + body instead of listing."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max results; each endpoint caps and defaults like the app."}],"responses":{"200":{"description":"Docs (or search hits).","content":{"application/json":{"schema":{"type":"object","description":"Docs (or search hits)."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}},"post":{"summary":"Create a doc as the person","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","body"],"properties":{"title":{"type":"string"},"body":{"type":"string","description":"Full Markdown body."},"parent_id":{"type":"string","description":"Folder to create in."}}}}}},"responses":{"200":{"description":"The created doc id.","content":{"application/json":{"schema":{"type":"object","description":"The created doc id."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/docs/{id}":{"get":{"summary":"Read a doc's Markdown body","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Doc id."}],"responses":{"200":{"description":"The doc.","content":{"application/json":{"schema":{"type":"object","description":"The doc."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}},"patch":{"summary":"Replace a doc's body","description":"A doc that mirrors the repo's rules file ships the edit as a pull request instead — the response says which happened.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Doc id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"}}}}}},"responses":{"200":{"description":"Save (or PR) confirmation.","content":{"application/json":{"schema":{"type":"object","description":"Save (or PR) confirmation."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/tasks":{"get":{"summary":"List tasks/epics in the workspace tracker","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["backlog","todo","doing","in_review","done","canceled"]},"description":"Filter by status."},{"name":"assignee","in":"query","required":false,"schema":{"type":"string"},"description":"'me' or a user/agent id."},{"name":"epic_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by parent epic."},{"name":"channel_id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by project channel."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["task","epic"]},"description":"Filter by kind."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Text search over title + description."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max results; each endpoint caps and defaults like the app."}],"responses":{"200":{"description":"A compact triage index.","content":{"application/json":{"schema":{"type":"object","description":"A compact triage index."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}},"post":{"summary":"File a task or epic as the person","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"description":{"type":"string","description":"Markdown body."},"kind":{"type":"string","enum":["task","epic"]},"status":{"type":"string","enum":["backlog","todo","doing","in_review","done","canceled"]},"priority":{"type":"integer","description":"0 none, 1 urgent, 2 high, 3 medium, 4 low."},"epic_id":{"type":"string"},"channel_id":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"The created task's number and T-ref.","content":{"application/json":{"schema":{"type":"object","description":"The created task's number and T-ref."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/tasks/{id}":{"patch":{"summary":"Update a task — only fields present in the body change","description":"Response echoes {ok, number, ref}; re-read through the list to see the new state. Merging a linked PR auto-completes the task.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Task uuid or T-<n> ref."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string","description":"Replace the description."},"append_note":{"type":"string","description":"Append a dated progress line instead of replacing."},"status":{"type":"string","enum":["backlog","todo","doing","in_review","done","canceled"]},"priority":{"type":"integer"},"epic_id":{"type":"string"},"channel_id":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}},"assignee_agent_id":{"type":"string"},"assignee_user_id":{"type":"string"},"pr_url":{"type":"string"},"pr_number":{"type":"integer"},"repo_full_name":{"type":"string"},"branch":{"type":"string"}}}}}},"responses":{"200":{"description":"Update confirmation.","content":{"application/json":{"schema":{"type":"object","description":"Update confirmation."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"404":{"description":"Not accessible. Deliberately identical for missing and forbidden — the API never confirms that something the token can't reach exists.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_request","not_found","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."}}}}}}}}}}},"/api/v1/openapi.json":{"get":{"summary":"This document","security":[],"responses":{"200":{"description":"The OpenAPI 3.1 spec.","content":{"application/json":{"schema":{"type":"object","description":"The OpenAPI 3.1 spec."}}}}}}}}}