Start one autonomous coding run against a repo in the caller's org

POST /v1/agents/coding

Runs a coding task on a repository: clones it into a sandbox, lets a model read and edit the code, run the tests, and push the work to a branch. Say the thing you want done — "fix the failing auth test in hanzoai/cloud" — and the run infers the repo, the branch and the plan. No prefix, no ceremony.

It answers 202 with the run's handle the moment the run is ADMITTED — not when it finishes. A coding run takes minutes; holding a request open for one would tie a connection to a model loop and give the caller nothing it cannot get better from the session stream.

The handle is a session id, and that is deliberate: the session is already the run's durable record and its live stream (/v1/agents/sessions/{id}/stream), so this door does not grow a progress endpoint, a status endpoint or a cancel endpoint of its own. One way to watch a run, whoever started it.

It is also how work CONTINUES. Pass an earlier run's session as after and this one starts from where that one stopped, so "now add tests for it" builds on the branch already pushed instead of a fresh clone. The follow-up still gets its own branch and its own session — one run, one branch, always reviewable on its own.

Request

12 fields, body application/json (required).

Response

202 body — 5 fields.

Failure carries the platform error shape — see Errors.

Examples

import { Configuration, AgentsApi } from 'hanzoai';

const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAgentsCoding({ after: "<after>", agentRef: "<agentRef>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).post_agents_coding(after="<after>", agent_ref="<agentRef>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.AgentsAPI.PostAgentsCoding(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, agents_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = agents_api::post_agents_coding(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new AgentsApi(client).postAgentsCoding();

curl -X POST https://api.hanzo.ai/v1/agents/coding \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "after": "<after>",
       "agentRef": "<agentRef>"
     }'

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_agent_conversations"
         }
       }
     }'

Agents API · All Hanzo APIs · Interactive reference