{"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 → Coding-agent connections. 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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}},"paths":{"/api/v1/me":{"get":{"operationId":"getCurrentIdentity","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/me/mentions":{"get":{"operationId":"listMyMentions","summary":"What's addressed to the person — mentions, broadcasts, DMs","description":"Messages addressed to the token's person, decided by the same rule as the app's notifications: @-mentions of their handle, @channel/@here/@everyone broadcasts, and messages in their DMs. Each row carries `reason` ('mention' or 'dm') and the lead-up `context`. Persist the newest `created_at` and pass it back as `since` to resume. `wait_ms` long-polls: the server holds the request (capped at 25s) and answers the moment something arrives.","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"Only messages after this ISO timestamp (the client-persisted cursor)."},{"name":"channel_id","in":"query","required":false,"schema":{"type":"string"},"description":"Optional channel filter."},{"name":"wait_ms","in":"query","required":false,"schema":{"type":"integer"},"description":"Long-poll hold in ms (capped at 25000). Omit for an immediate answer."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max results; each endpoint caps and defaults like the app."}],"responses":{"200":{"description":"Addressed messages, newest first.","content":{"application/json":{"schema":{"type":"object","description":"Addressed messages, newest first."}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/me/wake":{"get":{"operationId":"getWakeChannel","summary":"Realtime doorbell for instant pickup","description":"A Supabase Realtime broadcast topic that receives a content-free `wake` event whenever anything is posted in the workspace. Subscribe and treat each ping as \"GET /me/mentions now\". The topic is a secret and can rotate — re-fetch every `refreshMs` and on reconnect. The ping carries no content and is not a mention filter; keep polling as the source of truth.","responses":{"200":{"description":"Doorbell coordinates: url, anonKey, topic, event, refreshMs.","content":{"application/json":{"schema":{"type":"object","description":"Doorbell coordinates: url, anonKey, topic, event, refreshMs."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels":{"get":{"operationId":"listChannels","summary":"Channels the person can see, DMs included","description":"Lists every channel and direct message the token's person can currently read in this workspace.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/messages":{"get":{"operationId":"listChannelMessages","summary":"Recent messages in a channel","description":"Returns the newest window of top-level messages (default 30, max 200), oldest first. `hasMore: true` says more messages exist past the window and `cursor` is the message id to continue from: pass it as `?before=` for the next older page, or read forward from an anchor with `?after=`. Use the thread endpoint for replies.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max messages to return (default 30, max 200)."},{"name":"before","in":"query","required":false,"schema":{"type":"string"},"description":"A message id in this channel; return only older messages (paging upward from a previous cursor)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"A message id in this channel; return only newer messages, oldest first."}],"responses":{"200":{"description":"Messages, oldest first.","content":{"application/json":{"schema":{"type":"object","description":"Messages, oldest first."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"post":{"operationId":"createChannelMessage","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/automations":{"get":{"operationId":"listChannelAutomations","summary":"The channel's automations, with recent run history","description":"Members can read; the response says whether the caller may change them (isAdmin).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"Automations + isAdmin.","content":{"application/json":{"schema":{"type":"object","description":"Automations + isAdmin."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"post":{"operationId":"upsertChannelAutomation","summary":"Create or update an automation (workspace admins only)","description":"Triggers: message (contains/hasAttachment) | schedule (everyMinutes ≥15) | pr_merged | checks_failed | task_completed | run_settled | webhook (the response carries a ONE-TIME webhookKey + webhookPath). Actions (1-5): post_message (templates {{author}}/{{text}}/{{channel}}) | add_reaction | ask_agent (files a task and proposes a dispatch — a person approves in the channel before the agent runs; an automation can ask, never spend). Definitions are validated by the engine's own parsers. Pass automation_id to update, enabled to toggle.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","trigger","actions"],"properties":{"automation_id":{"type":"string","description":"Existing automation to update."},"name":{"type":"string"},"trigger":{"type":"object","description":"The trigger definition (see description)."},"actions":{"type":"array","items":{"type":"object"},"description":"1-5 action steps (see description)."},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The automation id.","content":{"application/json":{"schema":{"type":"object","description":"The automation id."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"403":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/automations/{automationId}":{"patch":{"operationId":"setChannelAutomationEnabled","summary":"Turn one automation on or off (workspace admins only)","description":"Changes only the enabled state. Re-enabling resets the scan watermark to database time in the same state transition, so messages and schedule slots missed while the automation was off do not replay.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."},{"name":"automationId","in":"path","required":true,"schema":{"type":"string"},"description":"Automation id."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160},"description":"Stable retry key. Equivalent to requestId over MCP."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The automation id and enabled state.","content":{"application/json":{"schema":{"type":"object","description":"The automation id and enabled state."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"403":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"409":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"delete":{"operationId":"deleteChannelAutomation","summary":"Delete one automation (workspace admins only)","description":"Deletes the automation and its run history. Send Idempotency-Key to make a retry return the original action receipt without repeating the delete.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."},{"name":"automationId","in":"path","required":true,"schema":{"type":"string"},"description":"Automation id."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160},"description":"Stable retry key. Equivalent to requestId over MCP."}],"responses":{"200":{"description":"The deleted automation id and action receipt.","content":{"application/json":{"schema":{"type":"object","description":"The deleted automation id and action receipt."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"403":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"409":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/env":{"get":{"operationId":"listChannelEnv","summary":"The room's environment values, by name","description":"Names, kinds, fingerprints, and last use for the room's environment (1029). Values are write-only and are never returned by any endpoint. The fingerprint is the first six hex characters of the SHA-256 of the value, so a caller can tell whether hilos holds the same value another system does.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"Names and fingerprints.","content":{"application/json":{"schema":{"type":"object","description":"Names and fingerprints."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"put":{"operationId":"setChannelEnvValue","summary":"Create or replace one environment value (workspace admins only)","description":"Available only when the teamspace's hosted_zero_to_one feature is enabled. Stores one value for the room. The name is uppercase letters, digits, and underscores, starting with a letter. `kind` is secret (default) or plain. The value goes to Supabase Vault, reaches hilos-owned verify commands, and is synchronized as a Vercel Preview variable when hilos deploys that run's branch. hilos never returns it or places it in model context, transcripts, run rows, cards, the action ledger, or hilos application logs. Project code executed by a check or Preview build can access and print or transmit it, so scope values to code you trust.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","description":"DATABASE_URL-shaped name."},"value":{"type":"string","description":"Write-only; never read back."},"kind":{"type":"string","enum":["secret","plain"]}}}}}},"responses":{"200":{"description":"The name and its fingerprint.","content":{"application/json":{"schema":{"type":"object","description":"The name and its fingerprint."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"delete":{"operationId":"deleteChannelEnvValue","summary":"Remove one environment value by name (workspace admins only)","description":"Available only when the teamspace's hosted_zero_to_one feature is enabled. Deletes the named value and its Vault secret. It stops reaching hilos-run verify commands immediately; the next hilos-owned branch deploy synchronizes the complete room set and removes it from that Vercel Preview environment. Answers status removed or not_found.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."},{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"The environment value's name."}],"responses":{"200":{"description":"Removed or not found.","content":{"application/json":{"schema":{"type":"object","description":"Removed or not found."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/budget":{"get":{"operationId":"getChannelBudget","summary":"The room's monthly agent budget and where it stands","description":"The room's monthly credit budget (1061), this month's allowance, credits used so far, credits remaining, `metered` (false for a billing-exempt workspace, whose runs are not budgeted and always start), `nextRunAllowed`, and the level: ok, warning (past 80 percent), paused (new runs stop until an owner or admin lifts it), or unknown (the spend could not be read, and runs stop until it can). The level accounts for the credits a new run would reserve, so paused means the next run really will not start. `monthlyCredits` null means the room has no budget, which is the default.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"The budget and where the room stands.","content":{"application/json":{"schema":{"type":"object","description":"The budget and where the room stands."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"put":{"operationId":"setChannelBudget","summary":"Set or clear a room's monthly agent budget (workspace admins only)","description":"Sets the room's monthly credit budget. Send null to clear it. A room at its budget pauses new hosted runs and posts a card an owner or admin lifts, either by allowing more credits for the month or by raising the budget.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["monthlyCredits"],"properties":{"monthlyCredits":{"type":["integer","null"],"minimum":1,"maximum":100000,"description":"Credits per calendar month, or null for no budget."}}}}}},"responses":{"200":{"description":"The saved budget and where the room stands.","content":{"application/json":{"schema":{"type":"object","description":"The saved budget and where the room stands."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/workspace":{"get":{"operationId":"getChannelWorkspace","summary":"Stored warm-workspace status for a room","description":"The room's warm workspace (1079): `status` is warm, stale, building, or absent, with its size in bytes, when it was built, when a run last used it, and `detail`, the same one-line summary the room's settings show. When Warm workspaces is enabled, a warm row restores on the next run and a stale row restores then re-installs; otherwise runs start cold even if a saved row remains. The storage handle is never returned.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"The room's workspace.","content":{"application/json":{"schema":{"type":"object","description":"The room's workspace."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/workspace/rebuild":{"post":{"operationId":"rebuildChannelWorkspace","summary":"Mark a room's warm workspace for rebuild (workspace admins only)","description":"Marks the room's workspace stale. When Warm workspaces is enabled, the next hosted run restores it, re-installs, and publishes it again; otherwise runs start cold until the feature is enabled. Deleting a workspace outright is room settings only. Returns the workspace's new status.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Channel id."}],"responses":{"200":{"description":"The workspace's new status.","content":{"application/json":{"schema":{"type":"object","description":"The workspace's new status."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/artifacts/{id}/address":{"put":{"operationId":"setArtifactAddress","summary":"Change the address a published native app lives at","description":"Moves the site to `<slug>.<sites domain>` (1035). The slug is a DNS label: 3 to 63 lowercase letters, digits, and hyphens, starting and ending with a letter or digit. Some names are reserved and some are already taken; both come back as 400. The address the app already holds is returned by the artifact reads as `site`. Guests cannot call this.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Native artifact id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","description":"The new first label of the address."}}}}}},"responses":{"200":{"description":"The new address.","content":{"application/json":{"schema":{"type":"object","description":"The new address."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/runs/{id}/retry":{"post":{"operationId":"retryRun","summary":"Retry a durable hosted run from where it stopped","description":"Re-enters a failed, canceled, or timed-out hosted run at its last completed step, reusing the coding step's output instead of running the model again (1036). Only runs on the durable engine can be retried — everything else answers 400, because on those lanes there is nothing to replay and a retry would silently be a new run. The requester or a workspace owner/admin only; guests cannot call this. If the run's sandbox is gone the engine starts it over with a note in the prompt saying the earlier attempt was interrupted.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Hosted run id, from the run's report card."}],"responses":{"200":{"description":"The run id that was put back in flight.","content":{"application/json":{"schema":{"type":"object","description":"The run id that was put back in flight."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/runs/{id}/events":{"get":{"operationId":"readRunEvents","summary":"Replay one run's ordered harness events","description":"Returns the redacted, runtime-neutral Harness Event Protocol ledger for a run after a per-run sequence cursor (1140). The default page is at most 100 events and the maximum is 200; pages stop earlier at a 128 KiB MCP-wire response budget. A single payload that cannot fit is projected as withheld without dropping its event sequence. Persist `nextAfter` as the next `after` cursor and continue while `hasMore` is true. The token must still be a non-guest member who can read the run's room. Guest roles receive 403; inaccessible and missing runs receive 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Durable run id."},{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"Return events with sequence greater than this cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200},"description":"Max events (default 100, max 200). A page may stop earlier at 128 KiB."}],"responses":{"200":{"description":"An ordered page of redacted harness events and its next cursor.","content":{"application/json":{"schema":{"type":"object","description":"An ordered page of redacted harness events and its next cursor."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"403":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/members":{"get":{"operationId":"listChannelMembers","summary":"People and agents in a channel, with paste-ready @mentions","description":"Lists the people and member agents visible in the channel, including a handle and ready-to-paste mention when available.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/channels/{id}/links":{"get":{"operationId":"listChannelLinks","summary":"Git artifacts linked to a channel (PRs, branches, repos) with live state","description":"Lists repository, branch, and pull-request links connected to the channel with their latest stored 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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/threads/{id}":{"get":{"operationId":"getThread","summary":"A thread: root message plus a window of replies, oldest first","description":"Returns the thread root and the newest window of replies (default and max 200) when the token can still read the containing channel. `hasMore: true` says more replies exist past the window and `cursor` is the message id to continue from: pass it as `?before=` for the next older page, or read forward from an anchor with `?after=`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The thread root message id."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max replies to return (default and max 200)."},{"name":"before","in":"query","required":false,"schema":{"type":"string"},"description":"A message id in this thread; return only older replies (paging upward from a previous cursor)."},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"A message id in this thread; return only newer replies, oldest first."}],"responses":{"200":{"description":"The thread.","content":{"application/json":{"schema":{"type":"object","description":"The thread."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/messages/{id}":{"patch":{"operationId":"updateMessage","summary":"Edit a message the person posted earlier (their own only)","description":"Replaces the Markdown body of one human-authored message owned by the token's person.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/message-link":{"get":{"operationId":"resolveMessageLink","summary":"Resolve a copied hilos message URL to the message and its context","description":"Parses a canonical hilos channel, message, or thread URL and returns the accessible conversation around it.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/search":{"get":{"operationId":"searchMessages","summary":"Search messages across everything the person can access","description":"Runs a contains search over readable workspace messages and returns newest matches first.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/docs":{"get":{"operationId":"listDocs","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"post":{"operationId":"createDoc","summary":"Create a doc as the person","description":"Creates a Markdown document in the workspace root or under the supplied parent folder.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","body"],"properties":{"title":{"type":"string","maxLength":200,"pattern":"^[^/]+$"},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/docs/{id}":{"get":{"operationId":"getDoc","summary":"Read a doc's Markdown body","description":"Returns one accessible workspace document, including its full Markdown body and hierarchy metadata.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"patch":{"operationId":"updateDoc","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. Pass expected_updated_at to make the write a compare-and-set: when the doc changed since that version, nothing is written and the response carries status \"conflict\" with the current body and author.","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"},"expected_updated_at":{"type":"string","description":"The doc's updated_at from when you read it, passed back verbatim. Omit to replace unconditionally."}}}}}},"responses":{"200":{"description":"Save (or PR) confirmation, or a conflict payload.","content":{"application/json":{"schema":{"type":"object","description":"Save (or PR) confirmation, or a conflict payload."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/tasks":{"get":{"operationId":"listTasks","summary":"List tasks/epics in the workspace tracker","description":"Returns a compact task and epic index, optionally narrowed by state, assignee, project, kind, or text.","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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"post":{"operationId":"createTask","summary":"File a task or epic as the person","description":"Creates a task or epic in the workspace tracker with optional project, labels, priority, and initial state.","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","minimum":0,"maximum":4,"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"}},"assignee_agent_id":{"type":"string","format":"uuid"},"assignee_user_id":{"type":"string","description":"Workspace member uuid, or 'me'."}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/tasks/{id}":{"patch":{"operationId":"updateTask","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","minimum":0,"maximum":4},"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","description":"A full http(s) url. An empty string unlinks; anything else that isn't a url is refused rather than clearing the link."},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/actions/{command}":{"get":{"operationId":"readAction","summary":"Run a manifest-declared read action","description":"The command must advertise the REST transport, be non-interactive, and have read risk. Query parameter names match that capability's input schema. Start with list_capabilities; mutations are refused on GET.","parameters":[{"name":"command","in":"path","required":true,"schema":{"type":"string"},"description":"Capability command from list_capabilities."},{"name":"arguments","in":"query","required":false,"schema":{"type":"object","additionalProperties":true},"style":"form","explode":true,"description":"Command-specific query parameters documented by its manifest inputSchema. Each key is sent as its own query parameter."}],"responses":{"200":{"description":"The command result.","content":{"application/json":{"schema":{"type":"object","description":"The command result."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"403":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"409":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}},"post":{"operationId":"mutateAction","summary":"Run a manifest-declared mutation","description":"Runs the same implementation as MCP, with the same live role/scope check and delegated-action receipt. Send Idempotency-Key on retries; the JSON body follows the selected capability's inputSchema.","parameters":[{"name":"command","in":"path","required":true,"schema":{"type":"string"},"description":"Capability command from list_capabilities."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":160},"description":"Stable retry key. Equivalent to requestId in the JSON body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Command-specific JSON. Use list_capabilities and select a capability that advertises the REST transport; its inputSchema is authoritative."}}}},"responses":{"200":{"description":"The result and delegated-action receipt.","content":{"application/json":{"schema":{"type":"object","description":"The result and delegated-action receipt."}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"401":{"description":"Missing, malformed, or revoked token.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"403":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"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","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"409":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}},"429":{"description":"Per-token rate limit hit; retry shortly.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["unauthorized","permission_required","invalid_request","not_found","conflict","rate_limited","internal"],"description":"Stable, machine-matchable."},"message":{"type":"string","description":"For humans; may change."},"hint":{"type":"string","description":"A concrete resolution or safe next step for the caller."}}}}}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"This document","description":"Returns the public OpenAPI 3.1 contract for the hilos REST API without requiring a token.","security":[],"responses":{"200":{"description":"The OpenAPI 3.1 spec.","content":{"application/json":{"schema":{"type":"object","description":"The OpenAPI 3.1 spec."}}}}}}}}}