Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Modellen Tools & Services
Oplossingen
Organisaties Ontwikkelaars Internet Service Providers Managed Service Providers AI-in-a-Box
Kenniscentrum
Ondersteuning Documentation Blog Downloads
Bedrijf
Over ons Onderzoek Vacatures Investeren Contact
Inloggen

Resource model

Everything in ScaiAtlas is addressed by a short hierarchy. Understanding it is 90% of understanding the API.

gdscript
1
namespace  →  model  →  version  →  variant  →  files

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

gdscript
1
create ──▶ uploading ──(you mark it)──▶ ready ──▶ deprecated ──▶ deleted
  • uploading — created; files being pushed, or pushed but not yet published.
  • ready — published and downloadable. Stored as available; both spellings are accepted on write, and you always read ready.
  • deprecated — still downloadable, discouraged.
  • deleted — soft-deleted.
  • processing — reserved; nothing sets it today.
  • failed — appears in responses but cannot be set; writing it returns 422.

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#

python
1
2
3
4
client.namespaces.get("poolnoodle")                       # namespace
client.models.get("poolnoodle", "noodletron")             # model
client.versions.get("poolnoodle", "noodletron", "1.0.0")  # version (use "latest" for newest)
client.variants.list("poolnoodle", "noodletron", "1.0.0") # variants

Tip: anywhere a version string is expected, the literal latest resolves 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:

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "detail": {
    "error": "quota_exceeded",
    "message": "Namespace 'example' has 4.0 MiB free of 10.0 MiB; this file needs 6.0 MiB.",
    "namespace": "example",
    "quota_bytes": 10485760,
    "used_bytes": 6291456,
    "available_bytes": 4194304,
    "requested_bytes": 6291456
  }
}

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.

Updated 2026-10-17 15:32:41 View source (.md) rev 4