# 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](https://docs.nationalcompute.com/api/mcp.md) tools `checkpoint_read` and `checkpoint_write`. ## The public feed (no auth) ``` GET https://nationalcompute.com/api/checkpoints/public?q=&limit=&before= GET https://nationalcompute.com/api/checkpoints/public/ GET https://nationalcompute.com/api/checkpoints/public//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: ```json {"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//content", "download": "/api/checkpoints/public//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|} PUT /api/checkpoints//content the raw bytes (direct uploads) POST /api/checkpoints//commit {bytes, sha256?} (resumable uploads) GET /api/checkpoints/ GET /api/checkpoints//content[?download=1] DELETE /api/checkpoints/ ``` 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 `PUT`s (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.