Resource model
Everything in ScaiAtlas is addressed by a short hierarchy. Understanding it is 90% of understanding the API.
1 | |
Namespace#
A namespace is an ownership and access-control boundary — one team, org, or project. It owns models and holds the member roster.
| Field | Meaning |
|---|---|
name |
Unique slug, 2–64 chars, ^[a-z0-9][a-z0-9-]*[a-z0-9]$ (e.g. poolnoodle). |
display_name |
Human-friendly name. |
visibility |
public (anyone), tenant (same ScaiKey tenant), or private (explicit members only). |
owner_tenant_id |
The tenant that owns the namespace. |
model_count |
Number of models inside. |
Visibility drives default read access; per-member roles (owner → admin → member → viewer) grant finer permissions. See Authentication.
Model#
A model is a named product inside a namespace (poolnoodle/noodletron). It carries
metadata that's stable across versions.
| Field | Meaning |
|---|---|
name |
Slug, 1–128 chars, ^[a-zA-Z0-9][a-zA-Z0-9._-]*$. |
full_name |
namespace/name (e.g. poolnoodle/noodletron). |
type |
One of the model types — llm, embedding, vision_language, … (required). |
license |
SPDX-style license id, optional. |
capabilities |
Free-form JSON describing what the model can do. |
modalities |
{input: [...], output: [...]} modality lists. |
tags |
Free-form labels for search and filtering. |
version_count, download_count |
Rollup counters. |
Version#
A version is an immutable, semantically-versioned release of a model.
| Field | Meaning |
|---|---|
version |
Semver: ^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$ (1.0.0, 2.1.0-beta.1). |
full_name |
namespace/model:version. |
format |
Primary format of the upload (safetensors, gguf, onnx, …). |
release_notes |
Human-readable notes for the release. |
requirements |
Free-form JSON of runtime requirements. |
files |
The file list, each with path, size, checksum_sha256. |
total_size, checksum_sha256 |
Aggregate size and manifest checksum. |
status |
Lifecycle — see below. |
variant_count |
Number of format variants attached. |
Version lifecycle (status)#
1 | |
uploading— created; files being pushed, or pushed but not yet published.ready— published and downloadable. Stored asavailable; both spellings are accepted on write, and you always readready.deprecated— still downloadable, discouraged.deleted— soft-deleted.processing— reserved; nothing sets it today.failed— appears in responses but cannot be set; writing it returns422.
Nothing promotes a version for you. It stays uploading, and refuses
downloads with 400, until you mark it ready. See
Version lifecycle for the whole
picture.
Variant#
A variant is an alternative representation of a version — typically a different format or quantization. The original upload is the primary variant; conversions (e.g. a GGUF Q4_K_M build of a safetensors original) are additional variants.
| Field | Meaning |
|---|---|
variant_name |
Slug, ≤64 chars (e.g. gguf-q4_k_m, awq-int4). |
format |
safetensors, pytorch, gguf, onnx, other. |
quantization |
Quantization label, if any (Q4_K_M, int4). |
is_primary |
true for the original upload. |
status |
pending → converting → available (or failed). Not renamed: a variant reads available, not ready. |
files |
The variant's files with checksums. |
Files#
The leaf level. Every file records a path (relative within the version/variant),
a size in bytes, and a checksum_sha256. Downloads verify these checksums; the
registry never hands out files whose bytes don't match.
Putting it together#
1 2 3 4 | |
Tip: anywhere a version string is expected, the literal
latestresolves to the highest published version — never one that is still uploading, and never a deprecated one. To address a version you are still uploading, name it.
Storage quotas#
A namespace may carry a limit in bytes. GET /api/v1/namespaces/{name}
reports quota_bytes and used_bytes; a null quota means no limit. Only a
tenant administrator can set or change one, so a namespace cannot lift its
own.
Uploads in flight count against the quota. Space is charged by
POST …/upload/init, before any bytes are sent, for two reasons: the parts
of an unfinished multipart upload really do occupy storage, and a caller
should be told a file will not fit before spending an hour sending it. It
also means the limit cannot be stepped past by opening several uploads at
once.
When a file does not fit, upload/init returns 507 Insufficient Storage and a body you can act on rather than parse:
1 2 3 4 5 6 7 8 9 10 11 | |
Deleting a version releases its space, and deleting now removes the stored files too, so usage and the bucket agree. An abandoned upload holds space until its version is deleted.