# HTTP API

> The registry API: authentication, search, downloads, publishing, device login, organizations and builds.

Source: https://dev.systemonemodels.tech/docs/api

The website is a client of this API with no privileged access: everything it
does is available to you.

- Base URL: `https://api.systemonemodels.tech`
- OpenAPI schema: [`/openapi.json`](https://api.systemonemodels.tech/openapi.json)
- Interactive reference: [`/docs`](https://api.systemonemodels.tech/docs)

## Authentication

Send a personal access token as a bearer token. Tokens start with `s1_pat_`
and are created at [Settings → Access tokens](https://dev.systemonemodels.tech/settings/tokens) or by
`systemone login`.

```bash
curl https://api.systemonemodels.tech/v1/auth/me -H "Authorization: Bearer $SYSTEMONE_TOKEN"
```

Browsers use a session cookie instead. Both are stored only as a SHA-256 hash.
Reading public models needs no credentials at all.

## Errors

Every failure has one shape, so clients can branch on `code`:

```json
{ "detail": "systemone.yaml is not valid", "code": "invalid_manifest",
  "errors": [{ "path": "license", "message": "unknown license 'apache2'" }] }
```

`401` means no or bad credentials, `403` not allowed, `404` not found (also
returned for private things you cannot see), `409` a conflict such as an
existing version, `422` invalid input, and `429` too many requests — wait for
the number of seconds in `Retry-After`.

## Finding models

```
GET /v1/search/models?q=routing&capability=route&architecture=laya&sort=latency
GET /v1/models/{namespace}/{name}
GET /v1/models/{namespace}/{name}/versions
GET /v1/models/{namespace}/{name}/lineage
```

| Search parameter | Meaning |
| --- | --- |
| `q` | Full text over name, summary, architecture and README; quoted phrases and `-exclusion` work |
| `capability`, `architecture`, `license`, `tag` | Repeatable facets |
| `namespace` | One owner only |
| `base_model` | Only fine-tunes of `namespace/name` |
| `sort` | `relevance`, `recent`, `stars`, `downloads`, `accuracy`, `latency` |
| `limit`, `offset` | Paging |

Results include facet counts over the current result set.

## Downloading files

```
GET /v1/models/{namespace}/{name}/resolve/{version}/{path}
```

Redirects to the file's bytes; `version` may be `latest`. The version
listing gives every file's path, size and SHA-256 — verify downloads against it.

## Publishing

1. `POST /v1/models` with `namespace`, `name`, `visibility` and
   `manifest_yaml` creates the repository (skip if it exists).
2. For each file, `POST /v1/models/{ns}/{name}/uploads` with `path`,
   `size_bytes` and `sha256`. The reply holds a presigned `url` to `PUT` the
   bytes to — or `parts` for files over 4 GB — or `already_present: true` when
   the registry already has that content.
3. `POST …/uploads/{upload_id}/complete` (with the parts' ETags for multipart).
4. `POST /v1/models/{ns}/{name}/versions` with `version`, `manifest_yaml`,
   optional `readme` and `notes`, and `artifacts` — one entry per completed
   upload (`kind: "r2"`, and the `uri`, `storage_key` and `path` that
   `complete` returned) — publishes them together. An artifact can also point
   at files hosted elsewhere, with `kind` `huggingface`, `github` or `url`.

Publishing needs a verified email address. A version string that already exists
returns `409` `version_exists`: versions never change once published.

## Signing in a CLI or device

The device authorization flow (RFC 8628):

```
POST /v1/auth/device                 → device_code, user_code, verification_uri, interval
POST /v1/auth/device/token           { "device_code": … } → 400 authorization_pending | slow_down | expired_token | access_denied, or the token
```

A person approves the `user_code` at `verification_uri` while signed in.

## Organizations, builds, notifications

```
POST /v1/orgs                               create an organization
GET  /v1/orgs/{name}/members
POST /v1/orgs/{name}/claims                 claim an organization listed on a company's behalf
GET  /v1/builds?kind=&use_case=&q=&model=   things built with System One models
POST /v1/builds                             submit one for review
GET  /v1/notifications
```

## Rate limits

Sign-up, sign-in, email codes, password resets and device-login requests are
limited per client address; over the limit the API answers `429` with
`Retry-After`. Reads are not limited by the API itself, and public pages are
cached at the edge.