> ## 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

> CLI 和控制台能做的事，你自己的程序也能做。

```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" }
```

这个接口不需要任何凭据，是确认「地址对不对」最快的办法。除它之外，所有接口都需要 bearer token。

## 基础地址

你所在部署的域名。StarForge 没有公共多租户服务——每套安装都是独立的一台服务器，地址由管理员提供。
同一个域名同时提供控制台、API，以及反向代理在 `/docs` 下的这份文档。

所有 API 路径都以 `/api/` 开头，只有两个例外：

| 路径                                  | 为什么不在 `/api/` 下                                                                         |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| `/inference/{deployment_id}/v1/...` | 打到[模型部署](/zh-Hans/api-reference/inference)的应用流量。路径短而稳定，好让它读起来就是一个普通的 OpenAI 兼容 base URL |
| `/healthz`                          | 容器和负载均衡探针，习惯上不带前缀                                                                       |

## 版本

两个版本号回答两个不同的问题。

<ParamField path="api" type="string">
  这个控制平面所讲的 JobSpec 方言，当前是 `forge/v2`。方言不一致的 CLI 根本无法在这里提交作业。
  从 `GET /api/version` 读取。
</ParamField>

<ParamField path="server" type="string">
  正在运行的 `starforge-console` 构建版本。报缺陷时有用；不要拿它做分支判断。
</ParamField>

REST 接口本身没有单独的版本号。接口只增不改：已有响应的结构被当作契约对待，因为控制台生成的类型依赖它。

## 请求与响应

* 请求体和响应体都是 UTF-8 的 JSON，请带上 `Content-Type: application/json`。
* 时间戳是带显式时区偏移的 ISO 8601：`2026-08-31T09:14:22+00:00`。
* 日志流和指标流是 Server-Sent Events，不是 JSON——相关接口会写明。
* 上传走签名 URL 握手，字节不经过控制平面：先申请 URL，PUT 上去，再登记。

## 列表

列表接口接受 `limit` 和 `offset`，直接返回数组，没有游标，也没有外层包装。

```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"
```

## 限流

只在滥用成本低的接口上按 IP 限流：登录每分钟 10 次，设备码轮询每分钟 20 次。超出返回 `429`。
其余接口控制平面不限流；部署方在网关上可能另有策略。

## 下一步

<Columns cols={2}>
  <Card title="认证" icon="key" href="/zh-Hans/api-reference/authentication" arrow="true">
    拿到 token、保持有效，以及为你要做的事挑对凭据种类。
  </Card>

  <Card title="错误" icon="triangle-alert" href="/zh-Hans/api-reference/errors" arrow="true">
    错误结构，以及常见拒绝到底意味着什么。
  </Card>

  <Card title="从训练代码回传" icon="chart-line" href="/zh-Hans/api-reference/ingest" arrow="true">
    训练作业把曲线送进控制台所讲的那份契约。
  </Card>

  <Card title="Python SDK" icon="python" href="/zh-Hans/api-reference/python-sdk" arrow="true">
    `starforge.report`——三个函数，不假设任何训练框架。
  </Card>
</Columns>