Create programmatic

POST /v1/exec/programmatic

Answers 501 — this deployment does not serve programmatic tool calling.

That sentence is the SUMMARY every projection shows, so it says what a caller gets rather than what the code does; the rest names what it would take to stop refusing.

/exec/programmatic is NOT this contract's sibling — it is a different protocol on an adjacent path: a multi-round-trip loop where the server suspends a Python program on a tool call, returns the pending calls with a continuation_token, and resumes when the client posts the results back (@hanzochat/agents ProgrammaticToolCalling). Implementing it means implementing suspension and resumption, which is a program, not an endpoint.

So it answers 501 with that fact rather than being routed into run, which would hand the caller a CodeResult its parser cannot read — a wrong answer, where this is a refusal a client can act on.

IT IS A TYPED OP, and the refusal for keeping it raw did not survive reading. It binds no body, opens no stream, relays no other process and sits on no wildcard, so none of the four wire facts that keep a route raw applies to it; what was cited instead was that a permanent stub should declare nothing. That argues for silence in the DOCUMENT and buys the silence everywhere else too — no MCP tool, no CLI command, no SDK method — so a caller could read this address and reach it by no projection but REST, and learn only by calling it that the protocol is not served. Declaring zip.WithStatus(501) is what makes typing honest: the document publishes the ONE status this route sends, over an Out with no schema, rather than the 204 a void op would otherwise have invented.

ONE delta, pinned by TestProgrammaticRefusesEveryBody: a body that is not JSON now answers 400 rather than 501, because op.invoke decodes before the handler is entered. Both are refusals of a protocol this deployment does not serve, no real caller sends one, and 400 is what the rest of the fleet answers to bytes it cannot parse.

It asks tenantOf for the reason every other operation here does, and the answer is the same on the wire it was: over HTTP the credential middleware has already run, so an admitted caller still reads 501. What the call closes is the entry point a route table cannot see — typing an operation makes it an MCP tool, which zip dispatches straight into the handler with no route and therefore no middleware. Uniformity is the whole property: every path into this subsystem reads the admission marker, so there is no operation anybody has to remember is the exception.

Request

The document declares no body for POST /v1/exec/programmatic. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask MCP's describe for post_exec_programmatic, which answers from the running route.

Response

Failure carries the platform error shape — see Errors.

Examples

hanzo exec programmatic

import { Configuration, ExecApi } from 'hanzoai';

const api = new ExecApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postExecProgrammatic();

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ExecApi(client).post_exec_programmatic()

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

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

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

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

let result = exec_api::post_exec_programmatic(&cfg, Default::default()).await?;

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

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

var result = new ExecApi(client).postExecProgrammatic();

curl -X POST https://api.hanzo.ai/v1/exec/programmatic \
  -H "Authorization: Bearer $HANZO_API_KEY"

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": "get_download"
         }
       }
     }'

Exec API · All Hanzo APIs · Interactive reference