Triggers a native build — an image, or the binaries a repo declares.

POST /v1/platform/runner

Triggers a native build — an image, or the binaries a repo declares.

The fabric's own build trigger, and what hanzo build and git-push-to-deploy call. It answers 202 with the build job id: a queued build, not a pushed artifact.

Two lanes, and a build is exactly one of them. The IMAGE lane takes repo and the output image and launches a BuildKit Job that pushes it. The ARTIFACT lane takes binaries — the same recipe the repo's hanzo.yml declares — and publishes to object storage instead; it must carry no image, because a build produces binaries or an image, never both.

PRIVILEGED, and A BUILD BELONGS TO THE ORGANIZATION ITS CREDENTIAL NAMES. Two credentials, never a third:

• one that NAMES an organization — a person who administers it (the hanzo build path, so one IAM login authorizes a build with no separate build token), or that organization's own machine identity (the pipeline path). The build is attributed to that org and confined to what it owns.
• the shared build-callback token, compared in constant time. It names NO organization, which is both why the fabric's own release can publish across brands with it and why anything that CAN name one is read first.

Both are bounded by the owned-registry allowlist. The org path is bounded again, by the org: the image's registry namespace must be one that organization owns, so it publishes into its own brand and can never overwrite another's through the shared push credential. The same confinement applies to the artifact lane's repo owner. There is no request field naming an organization — the attribution is read off the credential, so there is nothing for a caller to write it with.

The output image is parsed and validated as a single well-formed OCI ref before any authorization decision reads it, so a crafted ref cannot smuggle a build-exporter attribute past the check.

Request

22 fields, body application/json (required).

Response

202 body — 6 fields.

Failure carries the platform error shape — see Errors.

Examples

import { Configuration, PlatformApi } from 'hanzoai';

const api = new PlatformApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postPlatformRunner({ arch: "<arch>", args: {} });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PlatformApi(client).post_platform_runner(arch="<arch>", args={})

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

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

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

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

let result = platform_api::post_platform_runner(&cfg, Default::default()).await?;

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

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

var result = new PlatformApi(client).postPlatformRunner();

curl -X POST https://api.hanzo.ai/v1/platform/runner \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "arch": "<arch>",
       "args": {}
     }'

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

Platform API · All Hanzo APIs · Interactive reference