HTTP 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
• Interactive reference: /docs

Authentication

Send a personal access token as a bearer token. Tokens start with s1_pat_ and are created at Settings → Access tokens or by systemone login.

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:

{ "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.