REST API reference

Complete reference for the ScaiAtlas REST API. All routes are under /api/v1.

Base URL#

1

https://api.scaiatlas.io/api/v1

Interactive OpenAPI docs (Swagger UI at /docs, ReDoc at /redoc) are available on deployments running in debug mode.

Authentication#

Send a bearer token on every request (except the public auth endpoints noted below):

1

Authorization: Bearer <token>

Tokens prefixed sk_ are API keys; other tokens are validated as ScaiKey JWTs. Missing or invalid credentials return 401 with WWW-Authenticate: Bearer. See Authentication for the permission model.

Pagination#

List endpoints accept page (≥1) and page_size (1–100) query parameters and return a data array alongside flat pagination fields:

1
2
3
4
5
6
7

{
  "data": [ /* … */ ],
  "page": 1,
  "page_size": 20,
  "total": 137,
  "total_pages": 7
}

The Python SDK wraps this as PaginatedResponse[T]: iterate .items (an alias for data) or use the list_all() / *_all() helpers to walk every page. Its .pagination object surfaces page, per_page (= page_size), total_count (= total), total_pages, and computed has_next / has_prev.

Errors#

Errors return an appropriate 4xx/5xx status and a JSON body:

1

{ "error": { "code": "ATLAS_001", "message": "Human-readable message", "field": "name" } }

See Errors for the full list.

Conventions#

• A version path segment may be the literal latest to resolve the highest semver.
• 201 Created for creates, 202 Accepted for async work (variant conversion), 204 No Content for deletes.

Namespaces#

Base: /api/v1/namespaces

List accepts a visibility filter (public|tenant|private). Results are limited to public namespaces plus those in your tenant.

Create body (NamespaceCreate):

1

{ "name": "poolnoodle", "display_name": "Pool Noodle", "description": "…", "visibility": "tenant" }

• name — 2–64 chars, ^[a-z0-9][a-z0-9-]*[a-z0-9]$ (required)
• display_name — ≤255 chars, optional
• description — optional
• visibility — public|tenant|private (default tenant)

Returns 201 with a Namespace. The creator becomes owner. 409 if the name exists.

Namespace object:

PATCH body (NamespaceUpdate): display_name, description, visibility (all optional). DELETE: 204; 409 if the namespace still has models.

Members. Add-member body (NamespaceMemberCreate): exactly one of user_id / group_id, plus role (owner|admin|member|viewer). A NamespaceMember is { id, user: UserSummary|null, group: GroupSummary|null, role, granted_by, granted_at } where UserSummary = {id, email, display_name, tenant_id} and GroupSummary = {id, name, tenant_id}. The last owner cannot be demoted/removed (400).

my-permissions returns { role, permissions: [...], inherited_from: [{type, role, group_id, group_name}] }.

Models#

Base: /api/v1/namespaces/{namespace}/models

List accepts a type filter (a model type). Returns ModelSummary items.

Create body (ModelCreate):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "name": "noodletron",
  "type": "llm",
  "display_name": "Noodletron",
  "description": "…",
  "license": "apache-2.0",
  "capabilities": { "context_length": 8192 },
  "modalities": { "input": ["text"], "output": ["text"] },
  "metadata": { "params": "8B" },
  "tags": ["demo"]
}

• name — 1–128 chars, ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ (required)
• type — model type (required)
• display_name (≤255), description, license (≤64), capabilities (object), modalities ({input[], output[]}), metadata (object), tags (string[]) — all optional

Returns 201 with a Model. 409 if the name exists in the namespace.

Model object: id, namespace, name, display_name, description, type, license, capabilities, modalities, metadata, tags, version_count, download_count, created_by, created_at, updated_at. (ModelSummary is a lighter projection used in list/search: id, namespace, name, display_name, type, license, modalities, tags, latest_version, download_count, timestamps.)

PATCH body (ModelUpdate): display_name, description, license, capabilities, modalities, metadata, tags — all optional.

Versions#

Base: /api/v1/namespaces/{namespace}/models/{model}/versions

Create body (VersionCreate):

1
2
3
4
5
6
7
8

{
  "version": "1.0.0",
  "format": "safetensors",
  "release_notes": "Initial release.",
  "requirements": { "transformers": ">=4.40" },
  "quantization": null,
  "files": [ { "path": "model.safetensors", "size": 1234567, "checksum_sha256": "…" } ]
}

• version — semver ^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$ (required)
• format — 1–32 chars, validated against active formats, lowercased (required)
• release_notes, requirements (object), quantization — optional
• files — list of { path, size, checksum_sha256 }

Returns 201 with a Version (total_size summed from files, checksum pending until finalized). 400 for an unsupported format, 409 if the version exists.

Version object: id, model_id, namespace, model, version, full_name (namespace/model:version), version_major/minor/patch, version_prerelease, release_notes, requirements, format, quantization, files[] (each {path, size, checksum_sha256}, also exposed as name/sha256), total_size, checksum_sha256, status, variant_count, created_by, created_at, updated_at, published_at.

PATCH body (VersionUpdate): release_notes, status (version status) — optional.

Variants#

Base: /api/v1/namespaces/{namespace}/models/{model}/versions/{version}/variants

Create body (VariantCreate):

1

{ "variant_name": "gguf-q4_k_m", "format": "gguf", "quantization": "Q4_K_M" }

• variant_name — ≤64 chars (required)
• format — safetensors|pytorch|gguf|onnx|other (required)
• quantization — ≤32 chars, optional

Returns 202 Accepted with a Variant in pending status. 409 if the variant name exists; deleting the primary variant returns 400.

Variant object: id, version_id, variant_name, format, quantization, total_size, checksum_sha256, is_primary, status (variant status), files[] ({path, size, checksum_sha256}), created_at.

Upload#

Base: …/versions/{version}/upload — multipart, proxied to storage. Requires upload_version.

• UploadInit = { file_path, file_size (≥1), checksum_sha256 (64 hex), content_type }
• UploadInitResponse = { upload_id, file_id, part_size, part_count }
• UploadComplete = { parts: [ { part_number, etag } ] }

init returns 400 if the version isn't in uploading state.

Download#

Base: …/versions/{version}/download — proxied streaming. Requires download.

• /download query: variant (name), file (specific path). Returns { version_id, variant, total_size, file_count, files: [{path, size, checksum_sha256, url}] }.
• /download/files/{path} query: variant. Honors Range: bytes=start-end (→ 206 Partial Content, Content-Range); sets X-Checksum-SHA256, Accept-Ranges: bytes. 416 for an unsatisfiable range.

The version/variant must be in an available/ready state (400 otherwise).

Manifests (P2P)#

Base: …/versions/{version}/manifest

DistributionManifest: { version_id, variant_id, chunk_size, total_size, total_chunks, checksum_sha256, files: [ { path, size, checksum_sha256, chunks: [ { index, offset, size, checksum_sha256 } ] } ] }. GET returns 404 until generated; POST returns 409 if it already exists.

Search#

Base: /api/v1/search

Model search returns ModelSummary items; namespace search returns lightweight {id, name, display_name, description, visibility} objects. Both are scoped to public

• same-tenant results.

Options#

Base: /api/v1/options — the catalog of what the deployment supports.

Format = { id, name, display_name, description, file_extensions[], is_active, created_at, updated_at }. Quantization = { id, name, display_name, description, format_id, bits, is_active, created_at, updated_at }.

P2P#

Base: /api/v1/p2p — returns 503 if P2P is disabled on the deployment.

by-version returns { version_id, variant_id, total_peers, seeders, leechers, peers: [ { node_id, address, port, is_seeding, chunks_available, chunks_total, last_seen } ] }.

Auth#

Base: /api/v1/auth. Endpoints marked public need no token.

GET /auth/me → { id, email, display_name, tenant_id, permissions[], groups[] }.

Admin#

Base: /api/v1/admin. Elevated permissions required (tiered admin; formats/quantizations require super-admin).

Creating an API key (POST /admin/api-keys) returns the plaintext key once. Key bodies support permission_mode (explicit|inherited|restricted), linked_user_id, namespace_ids, and expires_in_days (1–365).

Access logs#

GET /api/v1/access-logs — filter by model_id, user_id, action, plus pagination; ordered newest-first. Non-super-admins see only their own tenant's logs. Each entry: { id, model_id, version_id, user_id, tenant_id, action, ip_address, user_agent, created_at, model_name, user_email }.

Files (filesystem backend)#

When the deployment uses filesystem storage, byte transfer happens through short-lived signed URLs (no bearer token; HMAC signature + expiry):

• PUT /api/v1/files/part?upload_id=…&part_number=…&expires=…&signature=… — upload a part.
• GET /api/v1/files/{key}?expires=…&signature=… — download a file.

(The same routes are also mounted under /api/v1/upload.) Invalid/expired signatures return 403.