# API endpoints

> Every REST API endpoint, grouped by what it acts on, read from the OpenAPI document at build — with parameters and a request you can build and copy.

Kind: reference · ~2 min · Verified v0.175.0 · Next: [Legacy HTTP routes](https://pr-1769-stg.superartifacts.app/docs/reference/http-api.md)

Every operation the [REST API](https://pr-1769-stg.superartifacts.app/docs/reference/api.md) answers, read from its OpenAPI document
when the docs are built. Open one for its parameters and a request built from the fields you
fill in. The request reads your key from the `SUPER_ARTIFACTS_KEY` environment variable, so
the key never goes into this page.

| Endpoint | Does | Parameters |
| --- | --- | --- |
| `GET /v1/whoami` | Account: Who this key publishes as | — |
| `GET /v1/help` | Account: How the operations fit together | topic (query) |
| `GET /v1/artifacts` | Artifacts: List your artifacts, newest first | — |
| `POST /v1/artifacts` | Artifacts: Publish an artifact, or a new version of one | slug (body, required), prompt (body, required), html (body), values (body), instances (body), template (body), title (body), description (body), kind (body), collection (body), visibility (body), policy (body), dataset (body), continues (body), uploads (body), valuesFile (body), files (body) |
| `GET /v1/artifacts/{artifact}` | Artifacts: One artifact: its versions, published version and declaration | artifact (path, required) |
| `PATCH /v1/artifacts/{artifact}` | Artifacts: Change visibility, gallery label, live phase or submission email | artifact (path, required), visibility (body), collection (body), phase (body), notifyOnSubmission (body) |
| `DELETE /v1/artifacts/{artifact}` | Artifacts: Delete an artifact with every version, permanently | artifact (path, required), confirm (query, required) |
| `GET /v1/artifacts/{artifact}/file` | Artifacts: Read one file of a version as text (default: the published index.html) | artifact (path, required), path (query), version (query) |
| `POST /v1/artifacts/{artifact}/open` | Artifacts: A ten-minute viewer URL for an artifact, private included | artifact (path, required), version (body) |
| `POST /v1/artifacts/{artifact}/versions/{version}/serve` | Artifacts: Serve an existing version again | artifact (path, required), version (path, required) |
| `POST /v1/artifacts/{artifact}/live` | Artifacts: Turn an artifact's live room on | artifact (path, required) |
| `DELETE /v1/artifacts/{artifact}/live` | Artifacts: Turn an artifact's live room off, disconnecting every visitor | artifact (path, required) |
| `POST /v1/uploads` | Artifacts: Stage big files for a publish; PUT each to its URL | files (body, required) |
| `GET /v1/artifacts/{artifact}/data` | Data: Rows visitors submitted to one artifact, newest first | artifact (path, required), filter (query), since (query), until (query), sort (query), limit (query), cursor (query), fields (query) |
| `POST /v1/artifacts/{artifact}/data/rows` | Data: Write rows into an artifact you may edit | artifact (path, required), stream (body), rows (body), ops (body), atomic (body) |
| `GET /v1/data` | Data: Rows submitted to a dataset or a gallery label | dataset (query), collection (query), filter (query), since (query), until (query), sort (query), limit (query), cursor (query), fields (query) |
| `POST /v1/data/query` | Data: Aggregate what was collected: numbers, never rows | scope (body), measures (body), agg (body), compute (body), filter (body), group_by (body), since (body), until (body), limit (body), distributions (body) |
| `GET /v1/schema` | Data: The data catalog: datasets and content collections, or a comparison | series (query), tags (query), artifact (query), compare (query), since (query), workspace (query) |
| `PUT /v1/schema` | Collections: Create or replace a content collection | define (body), workspace (body) |
| `GET /v1/collections/{collection}/entries` | Collections: One page of a content collection's entries | collection (path, required), workspace (query), filter (query), search (query), sort (query), direction (query), page (query), limit (query) |
| `POST /v1/collections/{collection}/entries` | Collections: Create one entry, or a batch | collection (path, required), values (body), status (body), workspace (body) |
| `POST /v1/collections/{collection}/entries/{entry}/fields/{field}/use` | Collections: Call an approved API with a stored secret you cannot read (workspace keys) | collection (path, required), entry (path, required), field (path, required), method (body, required), url (body, required), headers (body), body (body), header (body) |
| `GET /v1/templates` | Templates: Find, rank or list templates | request (query), scope (query), kind (query), sort (query), limit (query), jobs (query), audience (query), needs (query), cost (query), tier (query), mine (query) |
| `POST /v1/templates` | Templates: Create or revise a template draft | slug (body, required), title (body, required), description (body, required), kind (body), jobs (body), audience (body), useCases (body), installArchetype (body), installAfter (body), samplePublic (body), category (body), spec (body, required), guidance (body), prompt (body), sample (body), demo (body), files (body), companions (body), expectedVersion (body), changeNote (body) |
| `GET /v1/templates/{slug}` | Templates: One template in full, with its install prompt | slug (path, required), version (query) |
| `GET /v1/templates/{slug}/history` | Templates: A template's changelog | slug (path, required) |
| `GET /v1/templates/{slug}/feedback` | Templates: Comments on a template's artifacts, as themes | slug (path, required) |
| `POST /v1/templates/{slug}/actions` | Templates: Install, uninstall, rate, report, roll back or request verification | slug (path, required), action (body, required), stars (body), version (body), kind (body), reason (body), confirmedByPerson (body) |
| `POST /v1/templates/{slug}/release` | Templates: Release one version of your template | slug (path, required), version (body, required), visibility (body), demoConsent (body), sampleConsent (body) |
| `GET /v1/projects` | Projects: Your projects | workspace (query) |
| `POST /v1/projects` | Projects: Create a project, optionally seeded with artifacts | title (body), artifacts (body), groupLabel (body), visibility (body), rule (body), confirm (body), workspace (body) |
| `GET /v1/projects/{project}` | Projects: One project and its items | project (path, required), workspace (query) |
| `PATCH /v1/projects/{project}` | Projects: Rename, set visibility, reorder, move, fold groups or set a rule | project (path, required), title (body), visibility (body), order (body), move (body), rule (body), collapsedGroups (body), confirm (body), workspace (body) |
| `DELETE /v1/projects/{project}` | Projects: Delete a project; its artifacts stay | project (path, required), confirm (query, required) |
| `POST /v1/projects/{project}/artifacts` | Projects: Add artifacts to a project | project (path, required), artifacts (body), groupLabel (body), confirm (body), workspace (body) |
| `DELETE /v1/projects/{project}/artifacts/{remove}` | Projects: Remove one artifact (or item) from a project | project (path, required), remove (path, required) |
| `POST /v1/artifacts/{artifact}/shares` | Sharing: Give named people access to an artifact | artifact (path, required), emails (body, required), role (body) |
| `POST /v1/projects/{project}/shares` | Sharing: Give named people access to a project | project (path, required), emails (body, required), role (body), confirm (body) |
| `POST /v1/workspace/shares` | Sharing: Invite editors to a workspace (returns accept links) | emails (body, required), role (body), workspace (body) |
| `GET /v1/artifacts/{artifact}/comments` | Comments: Comment threads on an artifact, newest first | artifact (path, required), status (query), page (query), limit (query), cursor (query) |
| `POST /v1/artifacts/{artifact}/comments/responses` | Comments: Reply to and/or resolve threads, one outcome each | artifact (path, required), respond (body) |
| `GET /v1/artifacts/{artifact}/comments/screenshots/{screenshot}` | Comments: One message's screenshot, base64 in `image` | artifact (path, required), screenshot (path, required) |
| `GET /v1/mentions` | Comments: Where people @mentioned you; listing marks them seen | artifact (query), limit (query), cursor (query) |
| `GET /v1/signatures` | Signatures: An artifact's signature requests, newest first | artifact (query) |
| `POST /v1/signatures` | Signatures: Ask named people to sign one version of an artifact | artifact (body), version (body), signers (body), message (body) |
| `GET /v1/signatures/{request}` | Signatures: One signature request and its signers | request (path, required) |
| `POST /v1/signatures/{request}/remind` | Signatures: Email a signer their link again | request (path, required), signer (body) |
| `POST /v1/signatures/{request}/withdraw` | Signatures: Close an open signature request | request (path, required) |