StarForge API

Everything the CLI and the console do, your own tooling can do too.

curl https://starforge.your-company.com/api/version

{ "server": "0.3.0", "core": "0.3.0", "api": "forge/v2" }

That endpoint needs no credentials and is the fastest way to confirm you are pointed at a StarForge deployment. Everything else on this API needs a bearer token.

Base URL

Your deployment’s domain. There is no hosted multi-tenant StarForge — each installation is its own server, and your administrator gives you the address. The same host serves the console, the API, and (behind /docs) this site.

All API paths begin with /api/, with two deliberate exceptions:

Path	Why it is outside /api/
/inference/{deployment_id}/v1/...	Application traffic to a model deployment. Kept short and stable so it reads like any other OpenAI-compatible base URL
/healthz	Container and load-balancer probes, which are conventionally unprefixed

Versioning

Two version numbers answer two different questions.

api · string

The JobSpec dialect this control plane speaks, currently forge/v2. A CLI that speaks a different dialect cannot submit here at all. Read it from GET /api/version.

server · string

The build of starforge-console that is running. Useful in a bug report; not something to branch on.

The REST surface itself is not separately versioned. Endpoints are added; the shapes of existing responses are treated as a contract, because the console’s generated types depend on them.

Requests and responses

• Request and response bodies are JSON, UTF-8. Send Content-Type: application/json.
• Timestamps are ISO 8601 with an explicit offset: 2026-08-31T09:14:22+00:00.
• Log and metric streams are Server-Sent Events, not JSON — those endpoints say so.
• Uploads use a signed-URL handshake rather than posting bytes through the control plane. Ask for a URL, PUT to it, then register what you uploaded.

Lists

List endpoints take limit and offset and return the rows directly. There is no cursor and no envelope.

curl -H "Authorization: Bearer $SF_TOKEN" \
  "https://starforge.your-company.com/api/jobs?limit=50&offset=0"

Rate limits

Applied per-IP on the endpoints where abuse is cheap: 10 login attempts per minute, 20 device-code polls per minute. Exceeding one returns 429. The rest of the API is not rate limited by the control plane; a deployment behind a gateway may add its own.

Where to go next

Authentication

Get a token, keep it fresh, and pick the right kind for what you are building.

Errors

The error shape, and what the common rejections actually mean.

Reporting from training code

The contract a training job speaks to get curves into the console.

Python SDK

starforge.report — three functions, no framework assumptions.