Artifacts API

Publish self-contained HTML or Markdown pages to a shareable URL. Artifacts are versioned and permissioned, and update in place when you publish again.

This page is the REST reference. For the concepts and the CLI, see Artifacts, Publishing, Capabilities, and Sharing.

Responses use the standard envelope. See REST overview — response format.

Scopes

Read routes (list, get, content, render, frame, comments, assets, viewer, page store) need no scope. They apply the artifact's visibility instead: public and unlisted artifacts are readable without authentication, and everything else requires a caller who is allowed to see it.

A reader is served the artifact's one live version: the latest, or the pinned one. Version history is for editors, meaning the owner, a user shared with write permission, or a workspace member. GET /artifacts/{id}/versions answers a viewer with 403; GET /artifacts/{id}/versions/{versionId} and its content answer with 404. content, render and frame return 404 to a viewer who names a version other than the live one.

Both scopes are in the standard preset. See API keys — Permission scopes.

Endpoints

Artifact object

New artifacts are created private.

Version object

Publishing identical content is a no-op. No duplicate version is created.

Create or publish

POST /artifacts creates an artifact and its first version. When an artifact with the same name already exists in your namespace, it publishes a new version instead.

POST /artifacts/{id}/versions appends a version to an existing artifact.

Both accept multipart/form-data or JSON. Multipart is the recommended way to send page source.

Multipart

1curl -X POST https://api.inference.sh/artifacts \2  -H "Authorization: Bearer inf_your_key" \3  -F "[email protected]" \4  -F "title=Sales dashboard" \5  -F "type=html" \6  -F "capability=db"

1curl -X POST https://api.inference.sh/artifacts/art_abc123/versions \2  -H "Authorization: Bearer inf_your_key" \3  -F "[email protected]" \4  -F "label=v2"

JSON

1curl -X POST https://api.inference.sh/artifacts \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{5    "title": "Release notes",6    "type": "markdown",7    "content": "# v2.0\n\n- Faster renders"8  }'

Version conflicts

Pass base_version_id with the version_id you read before editing. When the artifact has moved past that version, the publish is refused with 409 and code version_conflict. The detail names the current version. Re-read it, merge, and publish again.

Update metadata

POST /artifacts/{id}

Updates title, description, favicon, images, or shared_version_id. Content changes go through a publish.

1{2  "title": "Updated title",3  "shared_version_id": "VERSION_ID"4}

shared_version_id pins a version, making it the live one viewers are served. Pass "" to make the latest version live again. Pinning changes which version is live; editors keep access to every version. See Sharing — Versions.

List and get

GET /artifacts or POST /artifacts/list returns artifacts you own or that were shared with you, with cursor pagination.

GET /artifacts/{id} returns one artifact by ID.

GET /artifacts/{namespace}/{name} resolves by name. Append @shortVersionId to the name to get that version attached instead of the latest (for example myteam/report@a1b2c3d4). For a viewer, a version other than the live one is 404.

GET /artifacts/{id}/versions or POST /artifacts/{id}/versions/list lists version metadata with cursor pagination. GET /artifacts/{id}/versions/{versionId} returns one version. Both require write access to the artifact: a viewer receives 403 from the list and 404 for a single version.

DELETE /artifacts/{id} deletes the artifact.

Content

GET /artifacts/{id}/content returns the source of the live version (latest, or the pinned version).

GET /artifacts/{id}/versions/{versionId}/content returns one version. versionId is a full ID or the short ID. Editors only; a viewer receives 404 for any version but the live one.

Render

GET /artifacts/{id}/render

Returns the page wrapped in a full HTML document, as belt artifact get --render prints it.

The response Content-Type is text/plain, so a browser shows the source instead of running it on the API origin. Browsers display published pages through Frame.

Frame

GET /artifacts/{id}/frame

Returns the URLs a client loads to show a published page. Both point at the user-content domain, never the API host. See Artifacts — Where a page runs. Accepts the same version and theme query parameters as Render, and runs the same read check as GET /artifacts/{id}. A viewer is framed the live version only; any other version is 404.

URL tokens are valid for about 10 minutes. Once a URL has been opened, the page stays accessible in that browser for about 55 minutes. Request a new frame after that.

1curl "https://api.inference.sh/artifacts/art_abc123/frame?theme=dark" \2  -H "Authorization: Bearer inf_your_key"

Authoring guidance

GET /artifacts/guidance

Returns the page contract with the design, capability, and diagram guidance. It is the text belt artifact guidance prints. No authentication required. The response body is text/markdown, not JSON.

Live updates

GET /artifacts/{id}/stream

Server-sent events for artifact updates such as new versions and metadata changes. See Streaming.

Visibility, sharing, transfer

POST /artifacts/{id}/visibility

1{ "visibility": "unlisted" }

POST /artifacts/{id}/share shares with one user:

1{ "user_id": "USER_ID", "permission": "read" }

permission is read (viewer: the live version) or write (editor: can publish versions and read the version history). GET /artifacts/{id}/shares lists shares. DELETE /artifacts/{id}/share/{userId} revokes one.

POST /artifacts/{id}/transfer moves the artifact to another workspace:

1{ "team_id": "TEAM_ID" }

→ Sharing

Comments

GET /artifacts/{id}/comments returns an array of threads. Each thread is a root comment with its replies in chronological order. Anyone who can read the artifact can list its threads.

POST /artifacts/{id}/comments requires artifacts:read.

Comments are disabled on public artifacts. The request returns 409 with code comments_unavailable.

POST /artifacts/{id}/comments/{commentId}/activate sets agent_activated on a thread root. Agents can read every thread but can only reply to or resolve activated threads.

POST /artifacts/{id}/comments/{commentId}/resolve resolves a thread. Send {"resolved": false} to reopen it.

Runtime capabilities

A page declares capabilities at publish time and gets only what its published version declared. Capabilities covers the window.inferencesh JavaScript API. The routes below are what the viewer calls on the page's behalf. Each is refused unless the artifact declared the matching capability.

Page store (db)

POST /artifacts/{id}/data/get, /data/list, /data/set, /data/update, /data/delete

set replaces a document and creates it when missing. update merges fields. Reads follow the artifact's visibility. Writes require a signed-in caller. Documents under data/users/me are private to the caller who wrote them.

A document response has collection, doc_id, data, updated_at, and owner_user_id (set for per-viewer documents). A list response has collection, documents, and count.

1curl -X POST https://api.inference.sh/artifacts/art_abc123/data/get \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"collection": "poll", "doc_id": "totals"}'

data/get returns 404 not_found with document not found when the artifact is readable but the document does not exist. data/list returns an empty documents array for an empty collection.

Viewer identity (user)

GET /artifacts/{id}/viewer

No email or credential is included.

Assets (assets)

Files stored beside an artifact. Page sources and assets are written to a dedicated private object store (not the shared bucket behind public task file URLs). Anyone who can view the artifact can read its assets through the API; upload and delete require artifacts:write. Uploading identical bytes twice returns the existing asset.

POST /artifacts/{id}/assets takes multipart form data with a file part and an optional content_type field.

1curl -X POST https://api.inference.sh/artifacts/art_abc123/assets \2  -H "Authorization: Bearer inf_your_key" \3  -F "[email protected]"

GET /artifacts/{id}/assets returns assets, count, total_bytes, and budget_bytes.

GET /artifacts/{id}/assets/{assetId} checks that the caller may view the artifact, then redirects (302) to a storage URL valid for 15 minutes, or streams the bytes.

DELETE /artifacts/{id}/assets/{assetId} removes the asset and its stored bytes.

Limits

A page store write over a limit returns 400 with code validation_error. Replacing an existing document is measured against the new payload only.

Related

• Artifacts — what a page is and where it runs
• Publishing — belt artifact publish, flags, updating in place
• Capabilities — db, user, assets from inside a page
• Sharing — visibility, pinned versions, comments
• API keys — artifacts:read and artifacts:write scopes