# Agent URL: https://docs.hanzo.ai/docs/openapi/agent > Autonomous agents for your org: define them, run them, keep every run. Also for this capability: **API** · [CLI](https://docs.hanzo.ai/docs/cli/agent) · [MCP](https://docs.hanzo.ai/docs/mcp-tools/agent) · [SDKs](https://docs.hanzo.ai/docs/sdks) Autonomous agents for your org: define them, run them, keep every run. > [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | -------------- | -------------------------------------- | | **Base URL** | `https://api.hanzo.ai` | | **Operations** | 57 | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | ## Specification Specification pending — no HIP in [hanzoai/hips](https://github.com/hanzoai/hips) declares `capability: agent` yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139. ## Four surfaces | Surface | Reaches this capability as | Coverage | | -------- | --------------------------------------------- | -------------------------------------------------------------------------- | | **REST** | `agent` at its own prefix | 57 operations | | **CLI** | `hanzo agent …` | 41 of 57 — the CLI pins the document on its own clock | | **SDK** | `AgentApi` in every published client | 57 methods | | **MCP** | tool `agent` on `https://api.hanzo.ai/v1/mcp` | 38 operations, 4 under the document's own id — ask `describe` for the rest | ## Quickstart ```bash export HANZO_API_KEY=sk-... # console.hanzo.ai → API keys ``` Then the first call — a read that needs nothing but the key. `GET /v1/agent`, operation `get_agent`: **CLI** ```bash hanzo agent list ``` **SDK** **.ts** ```ts import { Configuration, AgentApi } from 'hanzoai'; const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getAgent(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import AgentApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = AgentApi(client).get_agent() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.AgentAPI.GetAgent(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, agent_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = agent_api::get_agent(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.AgentApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new AgentApi(client).getAgent(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/agent \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** MCP reaches **agent** through the `agent` tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_agents" } } }' ``` Answers `200` with `object` — ok. ## Endpoints | Endpoint | What it does | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`POST /v1/agent/{ref}/run`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-by-ref-run) | Run one of your org's agents and get the recorded run back. | | [`GET /v1/agent/{ref}/runs`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-by-ref-runs) | Returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took. | | [`GET /v1/agent/{ref}/spend`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-by-ref-spend) | Answers what one of your org's agents has spent, in integer micro-USD. | | [`GET /v1/agent/{ref}`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-by-ref) | Returns one agent with its system prompt and its 20 most recent runs. | | [`PATCH /v1/agent/{ref}`](https://docs.hanzo.ai/docs/openapi/agent/patch-agent-by-ref) | Changes an agent in place. | | [`DELETE /v1/agent/{ref}`](https://docs.hanzo.ai/docs/openapi/agent/delete-agent-by-ref) | Removes an agent and every run recorded against it. | | [`GET /v1/agent/activity`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-activity) | Serves the org-wide recent-activity feed. | | [`POST /v1/agent/ask`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-ask) | The MCP server a coding run's harness asks its person through. | | [`GET /v1/agent/builds/{org}/{project}`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-builds-by-org-by-project) | Returns the readable build of one product: the agent session that produced it, turn by turn — the prompts, the reasoning, the commits each turn produced — plus the exact `git log` that re-derives every commit binding from git itself, so nothing here has to be taken on trust. | | [`GET /v1/agent/builds`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-builds) | Returns the public index of every published build, most recently updated first, so a gallery can link straight to the story behind each product. | | [`DELETE /v1/agent/chat/conversations/{id}/shares/{share}/viewers/{viewer}`](https://docs.hanzo.ai/docs/openapi/agent/delete-agent-chat-conversations-by-id-shares-by-share-viewers-by-viewer) | Remove one viewer from a link | | [`DELETE /v1/agent/chat/conversations/{id}/shares/{share}`](https://docs.hanzo.ai/docs/openapi/agent/delete-agent-chat-conversations-by-id-shares-by-share) | Revoke a link to one of your conversations | | [`GET /v1/agent/chat/conversations/{id}/shares`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-conversations-by-id-shares) | List the live links to one of your conversations | | [`POST /v1/agent/chat/conversations/{id}/shares`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-chat-conversations-by-id-shares) | Share one of your conversations by link | | [`GET /v1/agent/chat/conversations/{id}`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-conversations-by-id) | Read one agent thread in full | | [`GET /v1/agent/chat/conversations`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-conversations) | List the agent threads in your org | | [`POST /v1/agent/chat/conversations`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-chat-conversations) | Record turns in a conversation | | [`GET /v1/agent/chat/presets`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-presets) | List the agent presets available to a caller | | [`GET /v1/agent/chat/shared/{share}`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-shared-by-share) | Read a chat shared with you | | [`GET /v1/agent/chat/shared`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-shared) | List the chats shared with you | | [`DELETE /v1/agent/chat/shares/{share}`](https://docs.hanzo.ai/docs/openapi/agent/delete-agent-chat-shares-by-share) | Revoke any link in your organization | | [`POST /v1/agent/chat/shares/read`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-chat-shares-read) | Open a conversation shared by link | | [`GET /v1/agent/chat/shares`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-chat-shares) | List every live link in your organization | | [`POST /v1/agent/chat`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-chat) | Run one tool-calling round against your org's own tools | | [`GET /v1/agent/coding/{session}/artifacts`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-coding-by-session-artifacts) | Lists what a coding run left, kept after its sandbox is gone: every file it added or changed and its whole change as `changes.patch`, stored beside the run; the ports it served, each a preview while its sandbox is kept; its pull request and where its work was published. | | [`GET /v1/agent/coding/{session}/blob`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-coding-by-session-blob) | Returns one file of a coding run's repository, read where the tree is read, in the shape GET /v1/git/repos/{name}/blob answers: text verbatim, anything else base64, and a file past the 1 MiB view cap marked truncated with no content. | | [`GET /v1/agent/coding/{session}/changes`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-coding-by-session-changes) | Returns what a coding run changed, read from the forge it pushed its branch to: the commits on its branch that the base does not have, newest first; the net change of the branch against its base, one entry per file with that file's patch; and its pull request with the reviews it has had, or null while it has none. | | [`POST /v1/agent/coding/{session}/merge`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-coding-by-session-merge) | Merges a coding run's pull request into the branch it proposes into, on the forge the run pushed to, and answers the pull request after. | | [`GET /v1/agent/coding/{session}/tree`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-coding-by-session-tree) | Lists one directory of a coding run's repository, one level down with directories first: at the run's own branch once the forge holds it, and at the branch it started from until then — `ref` says which. | | [`POST /v1/agent/coding`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-coding) | Start one autonomous coding run against a repo in the caller's org | | [`POST /v1/agent/mcp/{server}`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-mcp-by-server) | The MCP address a coding run's harness reaches one of its org's MCP servers through. | | [`GET /v1/agent/metrics`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-metrics) | Serves the invocations-over-time histogram for the org's Agents dashboard. | | [`GET /v1/agent/runs`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-runs) | Returns the org's agent runs across EVERY agent, newest first — what ran here, for whom, on which model, how long it took, and why it failed. | | [`POST /v1/agent/sessions/{id}/budget`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions-by-id-budget) | Sets, raises, or removes a session's cap. | | [`GET /v1/agent/sessions/{id}/control`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-sessions-by-id-control) | Returns the steering commands (pause/resume/stop/message) recorded against the caller's own session that are newer than the cursor, oldest first, with the cursor to poll from next. | | [`POST /v1/agent/sessions/{id}/events`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions-by-id-events) | Records one turn of a session's transcript and answers 201 with it. | | [`POST /v1/agent/sessions/{id}/message`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions-by-id-message) | Sends a steering message to a running session — the endpoint a human or another agent interrupts through. | | [`POST /v1/agent/sessions/{id}/pause`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions-by-id-pause) | Asks a running session to pause. | | [`GET /v1/agent/sessions/{id}/progress`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-sessions-by-id-progress) | Returns how far along one run is: the share of its goal that is done, whether it is running, blocked or finished, and a line saying what it is doing right now. | | [`POST /v1/agent/sessions/{id}/resume`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions-by-id-resume) | Asks a paused session to continue, on the same terms as a pause. | | [`POST /v1/agent/sessions/{id}/stop`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions-by-id-stop) | Ends a running session. | | [`GET /v1/agent/sessions/{id}/tree`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-sessions-by-id-tree) | Returns the subagent-flow graph rooted at this session: the session, its children, their children, each node carrying its own event count. | | [`GET /v1/agent/sessions/{id}`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-sessions-by-id) | Returns one session with its direct child sessions and its 50 most recent events, oldest of those first. | | [`PATCH /v1/agent/sessions/{id}`](https://docs.hanzo.ai/docs/openapi/agent/patch-agent-sessions-by-id) | Updates a session's surface-owned truth: its status, its title, the run-target it is dispatched to, and the product it built plus whether that build's story is public. | | [`GET /v1/agent/sessions/stream`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-sessions-stream) | Live session and event updates for the caller's org, as Server-Sent Events. | | [`GET /v1/agent/sessions`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-sessions) | Returns the caller org's live sessions, newest first — each with its event count, its direct-child count and a one-line preview of its latest event. | | [`POST /v1/agent/sessions`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-sessions) | Opens a live agent session in the caller's org — the row every surface (the CLI's outer agent, hanzo.bot, the console, chat) hangs its activity off. | | [`POST /v1/agent/targets/{id}/claim`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-targets-by-id-claim) | The machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a runner is listening), and waits up to 25 seconds for the next run addressed to THIS machine. | | [`POST /v1/agent/targets/{id}/key`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-targets-by-id-key) | Mints (or rotates) the claim key a `hanzo code --serve` daemon presents to claim work for this machine, and returns it ONCE: only its SHA-256 hash is stored. | | [`POST /v1/agent/targets/{id}/runs/{runId}/report`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-targets-by-id-runs-by-runid-report) | Completes a claimed run: it delivers the terminal result to the run's durable owner, which is what lets that workflow finish. | | [`GET /v1/agent/targets/{id}`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-targets-by-id) | Returns one registered machine, with its live session load. | | [`PATCH /v1/agent/targets/{id}`](https://docs.hanzo.ai/docs/openapi/agent/patch-agent-targets-by-id) | Updates one machine in place. | | [`DELETE /v1/agent/targets/{id}`](https://docs.hanzo.ai/docs/openapi/agent/delete-agent-targets-by-id) | Deregisters one machine. | | [`GET /v1/agent/targets`](https://docs.hanzo.ai/docs/openapi/agent/get-agent-targets) | Returns every machine registered to the caller's org, newest first, each with its live session load. | | [`POST /v1/agent/targets`](https://docs.hanzo.ai/docs/openapi/agent/post-agent-targets) | Registers a machine as an agent target, or re-links one that is already registered. | | [`GET /v1/agent`](https://docs.hanzo.ai/docs/openapi/agent/get-agent) | Returns every agent defined in the caller's org, each with the number of runs recorded against it. | | [`POST /v1/agent`](https://docs.hanzo.ai/docs/openapi/agent/post-agent) | Defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names. | --- [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)