> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# StarForge API

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://starforge.your-company.com/api/version
```

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{ "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](/en/api-reference/inference). 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.

<ParamField path="api" type="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`.
</ParamField>

<ParamField path="server" type="string">
  The build of `starforge-console` that is running. Useful in a bug report; not something to branch on.
</ParamField>

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

<Columns cols={2}>
  <Card title="Authentication" icon="key" href="/en/api-reference/authentication" arrow="true">
    Get a token, keep it fresh, and pick the right kind for what you are building.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/en/api-reference/errors" arrow="true">
    The error shape, and what the common rejections actually mean.
  </Card>

  <Card title="Reporting from training code" icon="chart-line" href="/en/api-reference/ingest" arrow="true">
    The contract a training job speaks to get curves into the console.
  </Card>

  <Card title="Python SDK" icon="python" href="/en/api-reference/python-sdk" arrow="true">
    `starforge.report` — three functions, no framework assumptions.
  </Card>
</Columns>