Train

The cloud's one training endpoint, /v1/train (HIP-1333): clients the caller drives on the engine, and jobs the org's linked machines or Hanzo's executor run, whose adaptation, protection, objective and output are fields and whose artifacts, bases and evaluations are what they produce.

All API references → · Get started →

Base URL	`https://api.hanzo.ai`
Operations	24
Auth	`Authorization: Bearer $HANZO_API_KEY`

Specification

Specification pending — no HIP in hanzoai/hips declares capability: train 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	`train` at its own prefix	24 operations
CLI	—	no command reaches it yet — use HTTP or an SDK
SDK	`TrainApi` in every published client	24 methods
MCP	—	no tool names it yet — use HTTP or an SDK

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/train/jobs, operation get_train_jobs:

CLI

SDK

HTTP

MCP

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

.ts

.py

.go

.rs

.java

import { Configuration, TrainApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = TrainApi(client).get_train_jobs()

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

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

use hanzo_client::apis::{configuration::Configuration, train_api};

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

let result = train_api::get_train_jobs(&cfg, Default::default()).await?;

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

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

var result = new TrainApi(client).getTrainJobs();

curl https://api.hanzo.ai/v1/train/jobs \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP declares no tool for train — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

Answers 200 with object — ok.

Endpoints

Endpoint	What it does
`GET /v1/train/artifacts/{sha256}`	Answers one of the org's objects, as the list does, with an address that fetches its bytes for ten minutes once it is stored: how an executor reads an `artifact:<sha256>` dataset its job names, and how the org downloads what it uploaded.
`DELETE /v1/train/artifacts/{sha256}`	Deletes one of the org's objects — an upload or a job's output — from the store: every artifact naming it then reads deleted, and its storage is no longer billed.
`GET /v1/train/artifacts`	Answers the org's objects — its uploads and its jobs' outputs, one per sha256 — with what produced each, whether it is published and when retention deletes it.
`POST /v1/train/artifacts`	Records rows the org is about to upload, named by the SHA-256 of their bytes, and answers the same grant an executor's artifact gets: a presigned PUT S3 accepts only with that checksum and length, encrypted under the org's key — a PUT per 64 MiB part over 64 MiB — or stored: true when the org already holds those bytes.
`POST /v1/train/clients/{id}/forward_backward`	Accumulates the gradients of a batch on the client.
`POST /v1/train/clients/{id}/optim_step`	Applies the optimizer to the accumulated gradients.
`POST /v1/train/clients/{id}/sample`	Decodes from the client's current weights.
`POST /v1/train/clients/{id}/save_weights`	Writes the client's adapter on the engine.
`GET /v1/train/clients/{id}`	Answers one of the org's clients with its loss history.
`DELETE /v1/train/clients/{id}`	Drops one of the org's clients and frees its memory on the engine.
`GET /v1/train/clients`	Answers the org's live clients as the engine reports them.
`POST /v1/train/clients`	Loads base_model on the engine with a LoRA adapter and answers the client, loading; poll it until ready.
`GET /v1/train/jobs/{id}/artifacts`	Answers a job's artifacts — checkpoint, capability, lora, basis or merged, each named by the SHA-256 of its bytes — with a download address that lives ten minutes for each one stored.
`POST /v1/train/jobs/{id}/artifacts`	Records an output its executor is about to store, named by the SHA-256 of its bytes, and answers a presigned PUT for exactly that object under the org's prefix — S3 accepts it only with the checksum and encrypts it under the org's key — or, over 64 MiB, a presigned PUT per 64 MiB part, or stored: true when the org already holds those bytes.
`POST /v1/train/jobs/{id}/cancel`	Stops a job that has not ended.
`GET /v1/train/jobs/{id}/events`	Answers a job's events after a cursor — status changes, the coordinator's address, metrics, log lines, artifacts and the result — waiting up to `wait` seconds for the first new one, so a caller following a run holds one request at a time.
`POST /v1/train/jobs/{id}/events`	An executor's report for the task it holds: status changes, the lead's coordinator address, metrics, log lines, stored artifacts and, last, the lead's result.
`GET /v1/train/jobs/{id}/metrics`	Answers a job's metric series — loss, throughput and each validation suite's numbers as the executor reported them — one per name, each point [step, value, unix seconds].
`POST /v1/train/jobs/{id}/publish`	Publishes a job's output under a name.
`GET /v1/train/jobs/{id}`	Answers one job: what it asked for, its status and tasks, its artifacts, its result and verdict, and whether it was published.
`POST /v1/train/jobs/claim`	An executor's long poll for work: it names the machine it runs on, its devices and what its build runs, and is answered, within 25 seconds, one task it can run — a job's lead first; a join once its lead has said where it coordinates — or 204.
`GET /v1/train/jobs`	Answers the org's jobs, newest first, narrowed by ?status=.
`POST /v1/train/jobs`	Creates a job that teaches base_model one capability: the data, the objective, how the trained parameters are represented (adaptation), what they must not damage and by how much (protect), where it runs and how far (resources), the suites it is judged on (evaluation) and what it produces (output).
`GET /v1/train/models`	Answers each base the caller can train today, in one shape: the base, the methods it trains by (adaptations), where it runs (runs: Hanzo's devices or the org's machines) with what one device-second costs there in nano-USD, then the resources that run it (nouns), its executor and devices, and the protections, objective terms, outputs and dataset schemes it takes.

All Hanzo APIs · Interactive reference

Was this page useful?

PreviousML NextAgent