Bots
Package bots is a bot doing your work on a real desktop, live, while you watch.
Package bots is a bot doing your work on a real desktop, live, while you watch.
| Base URL | https://api.hanzo.ai |
| Operations | 3 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
bots
POST /v1/bots/{runId}/stop
Stop terminates one of the caller org's own bot runs and reports its terminal state.
The own-key guard is the org: it is the caller's validated org, never theirs to choose, and the runtime resolves the run id UNDER it. A run belonging to another tenant is not among this org's runs, so it answers absent — the same 404 a nonexistent id gets, which is what keeps this from being an oracle.
Absence is honoured ONLY when the runtime answers it. A runtime that does not serve stop reports nothing about the run, and reporting "stopped" on that basis would be a stop that cannot fail — so it is a 502.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
runId | path | string | yes |
POST /v1/bots/run
Reserved address for launching a bot run — not implemented, always 501
Answers 501 to every call. The bot runtime exposes no launch operation, so nothing here can start a sandbox, and this address is published rather than dropped because it is reserved: routes resolve by specificity, so the run literal can never bind as a run id against its neighbour /v1/bots/:runId/stop.
The refusal is total and takes no input. The handler never reads the body, so any bytes at all — malformed JSON included — get the same 501; no run id is minted, no session URL is handed back, and no per-run fee is charged. That is the point: the earlier version minted an id the runtime had never heard of, pointed it at a VNC node that did not exist, and took real money for it.
Listing and stopping runs are live and org-scoped. Only the launch is missing, and it returns in the same change that can prove a bot boots.
GET /v1/bots
List returns the caller org's live bot runs, read from the bot runtime and projected into the console contract with each run's live session URL derived here.
The org is ALWAYS the validated principal's org, NEVER a request field, and it is what scopes the runtime's answer — so one tenant can never enumerate another's runs. A runtime that cannot answer is an error, not an empty list: [] would tell the caller "your org has no runs", which is a different claim from "we could not ask", and the difference is the whole reason this endpoint exists.
How is this guide?