Hanzo AIDocs
Sign inAPI key

Create declare

Republishes what a registered runner can do, and answers with what this side understands, so the two learn about each other from one exchange.

POST /v1/runner/declare

Git → · All API references → · Get started →

Addresshttps://api.hanzo.ai/v1/runner/declare
MethodPOST
Operationpost_runner_declare
AuthAuthorization: Bearer $HANZO_API_KEY

Republishes what a registered runner can do, and answers with what this side understands, so the two learn about each other from one exchange.

Request

5 fields, body application/json (required).

FieldInTypeRequiredDescription
x-runner-uuidheaderstring—
x-runner-tokenheaderstring—
capabilitiesbodystring[]—Capabilities are the optional protocol behaviours this runner understands, e.g. "cancelling".
labelsbodystring[]—Labels replace what the forge holds, so a relabelled runner follows its configuration without re-registering.
versionbodystring—Version is the runner build now running.

Response

StatusBodyMeaning
200runner.DeclareOutok
defaultproblem-detailsrefused

200 body — 9 fields.

FieldInTypeAlwaysDescription
capabilitiesbodystring[]—Capabilities are what THIS FORGE understands, so a runner learns what the other side supports from the reply body rather than from a header.
runnerbodyrunner.Identity—
runner.ephemeralbodyboolean—Ephemeral means the runner takes ONE job and exits, so the forge must not expect it back.
runner.idbodyinteger (int64)—ID is the forge's own row id for this runner.
runner.labelsbodystring[]—Labels are what a workflow's runs-on: selects this runner by.
runner.namebodystring—Name is what a person calls this runner in the forge's UI.
runner.tokenbodystring—Token is the secret that authenticates that handle.
runner.uuidbodystring—UUID is the handle the runner presents on every later op.
runner.versionbodystring—Version is the runner build the forge last heard from.

Failure carries the platform error shape — see Errors.

Examples

hanzo runner declare
import { Configuration, GitApi } from 'hanzoai';

const api = new GitApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postRunnerDeclare({ capabilities: ["<capabilities>"], labels: ["<labels>"] });
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import GitApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = GitApi(client).post_runner_declare(capabilities=["<capabilities>"], labels=["<labels>"])
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.GitAPI.PostRunnerDeclare(context.Background()).Execute()
if err != nil {
	return err
}
use hanzo_client::apis::{configuration::Configuration, git_api};

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

let result = git_api::post_runner_declare(&cfg, Default::default()).await?;
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.GitApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new GitApi(client).postRunnerDeclare();
curl -X POST https://api.hanzo.ai/v1/runner/declare \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "capabilities": [
         "<capabilities>"
       ],
       "labels": [
         "<labels>"
       ]
     }'

MCP reaches git through the git 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:

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

Git API · All Hanzo APIs · Interactive reference

Was this page useful?
PreviousCreate workspaceNextCreate log