Checkpoints¶
A checkpoint is a static file a member of an organization published: an html report, a markdown write-up, an image, a dataset sample, model weights, any file. It is kept by National Compute and served back on demand. Every checkpoint belongs to one of two places:
- the organization — every member can find, open and download it from the console's Checkpoint pane or through the tools below;
- the public feed — a global list anyone can read, signed in or not.
Publishing there is National Compute's own for now: an organization's
public publish is refused (
403 forbidden,reason: public-restricted) and the console offers no Public choice.
The console's Marshall workspace publishes from a document pane (the
Publish button) and browses the organization's checkpoints in a checkpoint
pane; the console's Checkpoints page lists them and the public feed, each
row marked Organization or Public, with a viewer and a link per item;
Marshall itself publishes with checkpoint_publish and opens
items with checkpoint_open inside a workspace. Two interfaces reach
beyond the console: the anonymous public feed and the authenticated REST
family behind the MCP server tools checkpoint_read and
checkpoint_write.
The public feed (no auth)¶
GET https://nationalcompute.com/api/checkpoints/public?q=<text>&limit=<n>&before=<iso>
GET https://nationalcompute.com/api/checkpoints/public/<id>
GET https://nationalcompute.com/api/checkpoints/public/<id>/content[?download=1]
The list answers the live public items newest first, plus the platform's
own published documents, as {checkpoints: [...], more, cursor}; q
searches titles, descriptions and file names; before takes the previous
answer's cursor. Each item is:
{"id": "…", "title": "…", "description": "…", "filename": "report.html",
"content_type": "text/html; charset=utf-8", "bytes": 48213, "sha256": "…",
"visibility": "public", "status": "ready", "status_detail": "Public",
"publisher": {"org_display": "…", "username": "…"}, "revision": 2,
"published_at": "…", "created_at": "…",
"urls": {"content": "/api/checkpoints/public/<id>/content",
"download": "/api/checkpoints/public/<id>/content?download=1"}}
A platform document's publisher is {"name": "National Compute"}. The
feed shows the publishing organization's display name and the member's
username: both agreed to that when they published publicly.
/content streams the stored bytes with the stored content type,
X-Content-Type-Options: nosniff, Accept-Ranges: bytes (a Range
request answers 206), Cache-Control: no-store and, for html, SVG and
XML, a Content-Security-Policy: sandbox … header: a document opened
straight from the apex runs in an opaque origin. ?download=1 turns the
disposition into an attachment. Scripts are always attachments. Every
GET here carries Access-Control-Allow-Origin: *, so a page on any
origin may read the feed; OPTIONS answers 204.
An unknown id is 404 not-found. The feed lists an item only after review;
an item under review, rejected, or published to its organization alone is
not here.
The authenticated family¶
GET /api/checkpoints?scope=org&q&limit&before
POST /api/checkpoints {title, description?, filename, content_type, bytes,
visibility: org|public, upload?: direct|resumable,
sha256?, replace?: true|false|<id>}
PUT /api/checkpoints/<id>/content the raw bytes (direct uploads)
POST /api/checkpoints/<id>/commit {bytes, sha256?} (resumable uploads)
GET /api/checkpoints/<id>
GET /api/checkpoints/<id>/content[?download=1]
DELETE /api/checkpoints/<id>
Bearer: a member token, an OAuth session of the MCP server, or an organization API token (reads only; a token cannot publish). The same family answers the console's Marshall workspace on its own session.
Publishing is two calls. POST records the facts and answers
{id, revision, status: "pending", visibility, replaced, review: none|required,
upload}. With upload: direct (files up to 32 MiB) the answer carries
content_url: PUT the bytes there with the declared Content-Type. With
upload: resumable (any size up to 50 GiB) it carries a one-time storage
session_url and expires_at: upload the bytes to that session with
resumable PUTs (no credential of yours travels with them), then POST
…/commit with the final size. Either way the answer to the last call is
the item. Publishing the same file name again to the same place replaces
the item in place — the id stays, revision advances; replace: false
asks for a new item instead and 409 conflict with reason: exists
says one already lives.
Visibility. org items are live the moment the bytes land. public
is accepted from National Compute's own organization only (403 forbidden,
reason: public-restricted otherwise; the list's public_publish says in
advance). Accepted public items enter review: the item is visible to the organization with
status: "review" and status_detail: "Under review", National Compute
reviews it (an automated check assists; a person decides), and approval
moves it to the feed. A rejection leaves the item with the organization
and tells the publisher why (rejection_reason, visible to the creator
alone). A public replacement keeps the previous revision live until the
new one is approved.
Reading. The list is your organization's items in every state
(scope=org, the only scope; public or all answer 422 bad-request).
The feed is read through the anonymous route alone; a public item still
reads by id. Items you may act on carry can_delete: true.
Deleting is the publisher's alone: DELETE by the creator removes the
item for the organization and from the feed; copies already downloaded
are not recalled. Another member's id, an unknown id and a deleted id
answer 410 gone on this family (never 404, which here means the
feature is off).
Refusals¶
| Status | error |
When |
|---|---|---|
| 404 | not-found |
checkpoints are not enabled; or the item is unknown on the public feed |
| 410 | gone |
not your item, deleted, or unknown (bearer family) |
| 413 | too-large |
over the direct cap (limit_bytes) or the per-checkpoint cap |
| 422 | secret-detected |
the content looks like it carries a credential or token; nothing is stored |
| 422 | bad-request |
a field is missing or malformed (detail) |
| 409 | conflict |
reason: exists, not-pending, size-mismatch, sha-mismatch, object-missing, resumable-upload, wrong-status |
| 429 | org-cap |
the organization's checkpoint storage is full; delete something first |
| 403 | forbidden |
reason: public-restricted — a public publish from an organization the feed is not open to; or an organization API token tried to publish |
| 408 | upload-timeout |
a resumable session expired before its commit |
| Limit | Value |
|---|---|
| One direct upload (through the API) | 32 MiB |
| One checkpoint (resumable upload) | 50 GiB |
| Checkpoint storage per organization | 200 GiB |
| Title / description / file name | 200 / 4000 / 255 characters |
| List page | 50 items by default, 100 at most |
The MCP tools¶
checkpoint_read (action: list | search | get, q, id, limit,
before) answers your organization's items, the owner's view, and reads
any item by id; it never lists the public feed. checkpoint_write
(action: delete, id) deletes one of your own items in two phases: the
preview names the item, the confirm removes it. Publishing carries bytes
the MCP wire cannot, so it stays with the REST family and, inside a
workspace, with Marshall's checkpoint_publish. Both tools are absent
while checkpoints are not enabled for the platform.
What is never published¶
The content check refuses files that look like credentials or tokens
(.env, private keys, kubeconfigs, API keys in text) at every door: the
console, Marshall's tool and the API. Public items pass a content review
before they appear; items that fail stay with their organization.