{ "openapi": "3.1.0", "info": { "title": "23artifacts API", "version": "1.0.0", "summary": "Token-authenticated REST API for publishing artifacts", "description": "The scripted publishing surface of 23artifacts — file-native publishing for shell-capable agents and CI, which can't ride the MCP OAuth flow. It shares the publish pipeline with the MCP connector (https://23artifacts.com/mcp) and the dashboard; only the authentication differs.\n\n**Credentials.** Two kinds, both accepted as `Authorization: Bearer `:\n\n- **Publish token** — a standing credential minted in the dashboard (`/tokens`) or via the MCP `create_publish_token` tool. Covers every endpoint here.\n- **Upload session** — a short-lived, single-artifact capability minted via the MCP `create_upload_session` tool. It is handed out as a capability URL whose `?session=` query is the whole credential, so a plain `curl -X POST \"$URL\"` authenticates. A session covers exactly its own publish (`POST /api/v1/publish`, pinned to one project slug) and upload staging (`/api/v1/uploads*`) — nothing else.\n\n**Signed-in browsers.** No token needed from a browser that is signed in on this site: requests authenticate with the dashboard session automatically — the Test Request button in this reference included — and carry every scope, same as the dashboard. Session auth is same-origin only (a cross-origin `Origin` is refused); scripts and CI use tokens.\n\nInline publish caps: 25 MB per file, 50 MB per publish, 2000 files. Larger single files (up to 4 GB) are staged part-by-part through the resumable upload API and referenced from the publish as `{ \"path\": \"video.mp4\", \"upload\": \"\" }`; a publish with staged files may total 5 GB.\n\n\n\n**Scopes.** A publish token carries scopes chosen at mint time: `publish` (always present — the publish/staging/ingest surface every pre-scopes token had), `read` (the GET surface, including published file content), and `manage` (the management mutations). Endpoints below say which scope they need; a token without it gets 403. Upload sessions always carry `publish` alone.\n\nHuman-readable documentation: https://23artifacts.com/docs (agents: https://23artifacts.com/docs.md and https://23artifacts.com/llms.txt).", "contact": { "name": "23artifacts", "email": "hello@23artifacts.com", "url": "https://23artifacts.com" } }, "servers": [{ "url": "https://23artifacts.com" }], "security": [{ "publishToken": [] }, { "uploadSession": [] }, { "oauth2": [] }], "tags": [ { "name": "Publishing", "description": "Publish a new artifact or a new immutable version of an existing one." }, { "name": "Uploads", "description": "Resumable staging for files too large to inline (up to 4 GB per file). Stage, then reference the uploadId from a publish or an asset ingest." }, { "name": "Assets", "description": "The workspace's asset library: bulk ingest (publish scope; upload sessions don't cover it), search (read), and curation (manage)." }, {"name": "Artifacts", "description": "Detail, version history, promotion and rollback, deletion, tags, access, link previews, pretty slugs — the management surface (`read` / `manage` scopes)."}, {"name": "Share links", "description": "Revocable viewer-access URLs with per-link attribution and capabilities."}, {"name": "Reviews", "description": "The review loop: attach critiques, and read/write the collaborative comment stream — including the long-poll that makes an agent a live participant."}, {"name": "Rooms", "description": "The shared-state room viewers collaborate through: owner read, kill-switch, wipe."}, {"name": "Themes", "description": "The workspace's brand as data — tokens, CSS, guidance, deck layouts."}, {"name": "Decks", "description": "Editable slide-deck documents behind deck artifacts."}, {"name": "Guides", "description": "The platform documentation, credential-free."} ], "paths": { "/api/v1/attachments/{id}": { "get": { "tags": ["Reviews"], "operationId": "getAttachment", "summary": "Read an attachment's bytes", "description": "The bytes of one attachment. Authorization is the OWNING COMMENT'S — an attachment has no permissions of its own — so this 404s identically whether the id does not exist, the artifact is out of reach, the review's visibility excludes you, or the comment was hidden by its owner. Ink is served as `application/vnd.23artifacts.ink+json`, a type no browser renders; images keep the type their bytes were sniffed as. Requires the `read` scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The bytes.", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/me/web-session": { "post": { "tags": ["Identity"], "operationId": "createWebSession", "summary": "Hand this credential to a web view", "description": "Mints a ONE-TIME URL that turns this credential into a browser session, for a native client that needs a web view inside a gated artifact — a WKWebView has its own cookie jar and cannot read the browser's. Requires the `manage` scope: an OAuth session on this API already carries every scope, so this widens nothing for the app that mints it, but a read-only client must not be able to turn its token into a browser session. Redeemed once, within 60 seconds, at `/api/auth/handoff`; a session does not exist until then. Never returns a session token.", "parameters": [ { "name": "next", "in": "query", "schema": { "type": "string" }, "description": "Same-origin PATH to land on after redeeming. Anything else is ignored — a redirect that has just set a session cookie is worth more than an ordinary one." } ], "responses": { "200": { "description": "The one-time URL.", "content": { "application/json": { "schema": { "type": "object", "required": ["url", "expiresAt"], "properties": { "url": { "type": "string", "description": "Load this in the web view. Single use." }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Too many handoffs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/me": { "get": { "tags": [ "Artifacts" ], "operationId": "getMe", "summary": "Who this credential is", "description": "Identity, the organizations whose workspaces are reachable, and the scopes granted. Deliberately not scope-guarded: a credential that cannot answer “who are you” cannot render a signed-in state, and this exposes nothing its holder does not already own. Cheap enough for a native client to call on every cold launch to validate a restored token.", "responses": { "200": { "description": "The caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/publish": { "post": { "tags": ["Publishing"], "operationId": "publishArtifact", "summary": "Publish an artifact (or validate a payload)", "description": "Publishes the `files` array as a new artifact, or as a new immutable version when `project` names an existing slug. The same payload shape as the MCP `publish_artifact` tool.\n\n- New artifact: pass `name` (a slug is derived) or `project` to pick the slug explicitly. Slugs never change after creation.\n- Update: pass `project`; a new version is created at the same URL. `activate: false` stages it (shareable at its `versionUrl`) without going live.\n- `validate: true` dry-runs the full validation without publishing (free on bounded upload sessions) and returns the validation result instead of a publish result.\n\nAn upload-session credential is pinned to one slug: `project` may be omitted (the session's slug is the default) but must match if present.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" } } } }, "responses": { "200": { "description": "The publish result — or, with `validate: true`, the validation result.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PublishResult" }, { "$ref": "#/components/schemas/ValidateResult" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential doesn't cover this publish: an upload session pinned to a different slug, a session whose publishes are used up, or a workspace/plan rule refused it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict — e.g. the requested slug is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The payload is well-formed but unprocessable — e.g. the entrypoint isn't among the uploaded paths, or a referenced upload/asset can't be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/uploads": { "post": { "tags": ["Uploads"], "operationId": "createUpload", "summary": "Create a resumable upload", "description": "Declares one large file (up to 4 GB) for part-by-part staging. The response's `partSize` (16 MB unless configured otherwise) fixes the chunking: every part except the last must be exactly `partSize` bytes. Staging expires after 24 hours if never completed, and binds to the credential's workspace — the publish that references it must land in the same workspace.\n\nSend an `Idempotency-Key` header to make retries safe: a repeated create with the same key replays the original upload instead of opening a second one.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any stable string (max 200 chars). A retry with the same key returns the already-created upload." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadRequest" } } } }, "responses": { "200": { "description": "The staged upload to PUT parts against.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/uploads/{uploadId}": { "get": { "tags": ["Uploads"], "operationId": "getUpload", "summary": "Upload status", "description": "The upload's state and which parts have been received — resume by re-PUTting whatever `receivedParts` is missing. Uploads belonging to another workspace answer 404.", "parameters": [{ "$ref": "#/components/parameters/uploadId" }], "responses": { "200": { "description": "Current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/uploads/{uploadId}/parts/{partNumber}": { "put": { "tags": ["Uploads"], "operationId": "putUploadPart", "summary": "Upload one part", "description": "Sends part `partNumber` (numbered from 1) as a raw request body. Parts may arrive in any order; re-PUT a part to overwrite it — that's resume after a lost connection. Every part except the last must be exactly `partSize` bytes (from the create response); the last carries the remainder.", "parameters": [ { "$ref": "#/components/parameters/uploadId" }, { "name": "partNumber", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "1-based part index, at most ceil(size / partSize)." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Part stored.", "content": { "application/json": { "schema": { "type": "object", "required": ["n", "received"], "properties": { "n": { "type": "integer", "description": "The part number just stored." }, "received": { "type": "integer", "description": "Bytes received for this part." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The upload is not accepting parts (already complete, consumed, or aborted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "$ref": "#/components/responses/UploadExpired" }, "413": { "description": "The part body exceeds the upload's `partSize`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/uploads/{uploadId}/complete": { "post": { "tags": ["Uploads"], "operationId": "completeUpload", "summary": "Complete an upload", "description": "Verifies every part arrived and the total matches the declared `size`, then assembles the file. The server computes the authoritative sha256 in a streaming pass over the assembled bytes — it never trusts the client's claim for the digest publish will store. Completing an already-complete upload is a no-op (idempotent). The uploadId is then referenced from a publish (`{ \"path\": …, \"upload\": … }`) or an asset ingest (`{ \"upload\": … }`).", "parameters": [{ "$ref": "#/components/parameters/uploadId" }], "responses": { "200": { "description": "The assembled upload.", "content": { "application/json": { "schema": { "type": "object", "required": ["uploadId", "size", "state"], "properties": { "uploadId": { "type": "string" }, "size": { "type": "integer", "description": "Declared (and now verified) total size in bytes." }, "state": { "type": "string", "const": "complete" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Parts are missing, or the received total doesn't match the declared size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "$ref": "#/components/responses/UploadExpired" } } } }, "/api/v1/assets/{versionId}/raw": { "get": { "tags": ["Assets"], "operationId": "getAssetBytes", "summary": "Download one asset version's bytes", "description": "The image (or font) itself, for a `versionId` from list_assets. Requires a token carrying the `read` scope, and answers 404 — never 403 — for an asset outside the caller's workspace, so the id cannot be used to probe another library. Platform-library assets are readable by everyone.\n\nA versionId addresses exactly one set of bytes forever, so the response is `immutable` and safe to cache indefinitely; it is also `private`, being scoped to a credential.\n\nThe dashboard's equivalent (`/api/assets/{versionId}/raw`) authenticates with a session cookie and is not reachable with a token.", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "From an Asset's `versionId`." }, { "name": "organization", "in": "query", "schema": { "type": "string" }, "description": "Org slug — look in that organization's library instead of the token's own." } ], "responses": { "200": { "description": "The bytes.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/avif": { "schema": { "type": "string", "format": "binary" } }, "image/gif": { "schema": { "type": "string", "format": "binary" } }, "font/woff2": { "schema": { "type": "string", "format": "binary" } }, "font/woff": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/assets": { "post": { "tags": ["Assets"], "operationId": "ingestAssets", "summary": "Bulk-ingest assets into the workspace library", "description": "Stores a batch of images and web fonts (raster PNG/JPEG/WebP/AVIF/GIF plus woff2/woff; SVG is refused as a script-bearing format, a bare TTF/OTF is refused with a note to convert it; max 15 MB per asset) into the workspace's asset library, each reported independently so one bad file doesn't cost the rest. Bytes travel inline as base64, or by reference to a completed resumable upload.\n\n**Publish tokens only** — upload sessions are pinned to a single artifact's publish and don't cover this endpoint. Re-ingesting an existing `library/name` adds a version.", "security": [{ "publishToken": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetIngestRequest" } } } }, "responses": { "200": { "description": "Every asset stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetIngestResponse" } } } }, "207": { "description": "Partial success — some assets stored, some failed. Check each item's `ok`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetIngestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "Assets" ], "operationId": "listAssets", "summary": "Search the asset library", "description": "Images this workspace can use in artifacts — its own plus the curated platform library. `query` matches name, library, tags and the vision-generated description of what the image shows. Each result's `ref` (\"library/name\") is what a publish references as `{ path, asset }`. Requires a token carrying the `read` scope. MCP twin: list_assets.", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated; results must carry all." }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "user", "org", "platform" ] } }, { "name": "organization", "in": "query", "schema": { "type": "string" }, "description": "Org slug — act in that organization's workspace instead of the token's own." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Matching assets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Assets" ], "operationId": "setAssetMeta", "summary": "Edit asset metadata", "description": "Correct an asset's description or tags — the description is what search matches. One ref via `asset`, or many via `assets: [{asset, description, tags}, …]` (each entry reports its own result; 207 on partial failure). Requires a token carrying the `manage` scope. MCP twin: set_asset_meta.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string", "description": "\"library/name\" (single form)." }, "description": { "type": ["string", "null"], "maxLength": 500 }, "tags": { "type": "array", "items": { "type": "string" } }, "assets": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "description": { "type": ["string", "null"] }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "asset" ] } }, "organization": { "type": "string" } } } } } }, "responses": { "200": { "description": "The updated asset, or per-item batch results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/Asset" }, "updated": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "error": { "type": ["string", "null"] } } } } } } } } }, "207": { "description": "Batch partially failed — inspect `results`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "error": { "type": ["string", "null"] } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Assets" ], "operationId": "deleteAssets", "summary": "Remove assets from the library", "description": "Stops the asset(s) being listed or referenced by future publishes; artifacts that already used them are untouched. One ref via `asset`, or many via `assets`. Requires a token carrying the `manage` scope. MCP twin: delete_asset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "type": "string" }, "assets": { "type": "array", "items": { "type": "string" } }, "organization": { "type": "string" } } } } } }, "responses": { "200": { "description": "Deleted, or per-item batch results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": {}, "ref": { "type": "string" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "error": { "type": ["string", "null"] } } } } } } } } }, "207": { "description": "Batch partially failed — inspect `results`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" }, "error": { "type": ["string", "null"] } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts": { "get": { "tags": [ "Artifacts" ], "operationId": "listArtifacts", "summary": "List your artifacts", "description": "Artifacts in the token's workspace (`?organization=` overrides). Available to every token — listing has always been part of the publish surface. `query` and `tags` filter in SQL, so they hold across pages. Pagination is opt-in: without `limit` the whole workspace comes back, as it always has. MCP twin: list_artifacts.", "parameters": [ { "name": "organization", "in": "query", "schema": { "type": "string" }, "description": "Org slug — act in that organization's workspace instead of the token's own." }, { "name": "query", "in": "query", "schema": { "type": "string", "maxLength": 200 }, "description": "Case-insensitive substring match over slug and name." }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated; matches artifacts carrying ALL of them. Repeatable." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size. Omit for every artifact — the historical behaviour." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a previous response's `nextCursor`. Follow until it comes back null." } ], "responses": { "200": { "description": "The workspace's artifacts.", "content": { "application/json": { "schema": { "type": "object", "required": ["artifacts"], "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactSummary" } }, "nextCursor": { "type": ["string", "null"], "description": "Pass back as `cursor` for the next page; null when this is the last one. Always null unless `limit` was supplied." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/artifacts/{slug}": { "get": { "tags": [ "Artifacts" ], "operationId": "getArtifact", "summary": "Get an artifact", "description": "Detail and version history for an artifact you own. Requires a token carrying the `read` scope. MCP twin: get_artifact.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." } ], "responses": { "200": { "description": "The artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Artifacts" ], "operationId": "deleteArtifact", "summary": "Delete an artifact (soft)", "description": "Takes the artifact offline: its URL answers 410 Gone, the slug stays reserved, stored versions are retained; the shared-state room (viewer-authored) is deleted outright. Requires a token carrying the `manage` scope. MCP twin: delete_artifact.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts/{slug}/versions/{version}/files": { "get": { "tags": [ "Artifacts" ], "operationId": "getArtifactContent", "summary": "Read back published files", "description": "The source files of a published version — the canonical copy of anything you published. Authenticates with a dashboard session cookie OR a token carrying the `read` scope; plain publish tokens and upload sessions are refused, so a leaked CI credential can't exfiltrate content. Without `path`: the manifest, with content inlined for files that fit the response budget. With `path`: that single file in full. With `download=1`: the manifest plus per-file URLs to fetch out-of-band (no bytes inlined). Also served at /api/v1/projects/{slug}/versions/{version}/files (legacy spelling). MCP twin: get_artifact_content.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A version number, or `live`." }, { "name": "path", "in": "query", "schema": { "type": "string" }, "description": "Fetch this one file, uncapped." }, { "name": "download", "in": "query", "schema": { "type": "string", "enum": [ "1", "true" ] }, "description": "Manifest + fetch URLs only, no content inlined." } ], "responses": { "200": { "description": "Manifest with inline content, a single file, or (download) the URL manifest.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "versionNumber": { "type": "integer" }, "live": { "type": "boolean" }, "entrypoint": { "type": "string" }, "truncated": { "type": "boolean" }, "baseUrl": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer" }, "inlined": { "type": "boolean" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "content": { "type": "string" }, "url": { "type": "string" } } } } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "publishToken": [] }, {} ] } }, "/api/v1/artifacts/{slug}/analytics": { "get": { "tags": [ "Artifacts" ], "operationId": "getArtifactAnalytics", "summary": "Traffic analytics", "description": "Views, unique visitors (cookieless), time series, and top paths / referrers / countries / devices. Requires a token carrying the `read` scope. MCP twin: get_analytics.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." }, { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "all" ], "default": "7d" } } ], "responses": { "200": { "description": "The analytics summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts/{slug}/live-version": { "put": { "tags": [ "Artifacts" ], "operationId": "setLiveVersion", "summary": "Promote or roll back", "description": "Point the artifact's live URL at an existing version — promote a staged one or roll back. Takes effect within seconds. Requires a token carrying the `manage` scope. MCP twin: set_live_version.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "The new live pointer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLiveResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts/{slug}/tags": { "put": { "tags": [ "Artifacts" ], "operationId": "setArtifactTags", "summary": "Replace tags", "description": "The list you pass becomes the artifact's tags (empty array clears). Lowercase slugs, max 20. Requires a token carrying the `manage` scope. MCP twin: set_tags.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "tags" ] } } } }, "responses": { "200": { "description": "The stored tags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts/{slug}/access": { "put": { "tags": [ "Artifacts" ], "operationId": "setAccessPolicy", "summary": "Set who can view", "description": "Change viewer access without re-publishing: `public`, `private`, `email_otp`, `google`, `org_members` — one `type` or an OR-set via `types`. `config` carries allowlists (allowedDomains/allowedEmails/emailPattern) and REPLACES the stored one. Requires a token carrying the `manage` scope. MCP twin: set_access_policy.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPolicy" } } } }, "responses": { "200": { "description": "The stored policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "type": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts/{slug}/preview": { "put": { "tags": [ "Artifacts" ], "operationId": "setPreviewPolicy", "summary": "Set link-preview disclosure", "description": "What an unauthenticated unfurl (Slack, iMessage, crawlers) may reveal about a GATED artifact: `generic` (platform card, default), `title`, `custom` (authored title/description, optional screenshot), `full`. Anything above generic is visible to anyone holding the URL. Requires a token carrying the `manage` scope. MCP twin: set_preview_policy.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The artifact's slug (its subdomain)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewPolicy" } } } }, "responses": { "200": { "description": "The stored preview policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "level": { "type": "string" }, "title": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "includeScreenshot": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/artifacts/{slug}/pretty-slug": { "put": { "tags": [ "Artifacts" ], "operationId": "setPrettySlug", "summary": "Set the short-URL label", "description": "Give a PUBLIC artifact a memorable label on the short domain (-