# REST API

> Call Super Artifacts from your own code over HTTPS with an API key — base URL, errors, pagination, retries, rate limits, key scopes and MCP parity.

Kind: reference · ~3 min · Verified v0.175.0 · Next: [API endpoints](https://pr-1916-stg.superartifacts.app/docs/reference/api-endpoints.md)

Every [MCP tool](https://pr-1916-stg.superartifacts.app/docs/reference/mcp.md) has an HTTPS endpoint. See [API endpoints](https://pr-1916-stg.superartifacts.app/docs/reference/api-endpoints.md)
for operations, or use an [SDK](https://pr-1916-stg.superartifacts.app/docs/sdks.md).

## Base URL and key

Send JSON to `https://superartifacts.app/v1`. Create a key in
[Settings → API keys](https://superartifacts.app/settings/api-keys); send `Authorization: Bearer <key>`.
The public OpenAPI document is `https://superartifacts.app/v1/openapi.json`.

Keys allow reading, or reading and writing. A read key writing gets `403 scope_required`;
older keys allow both. Keep keys server-side: requests carrying `Origin` are refused with `403`.

## Errors

Failures use `{error: {code, message}}`. [Error codes](https://pr-1916-stg.superartifacts.app/docs/reference/errors.md) lists stable codes.

| Status | `code` |
| --- | --- |
| 400 | `invalid_arguments`, `invalid_*` |
| 401 | `unauthorized` |
| 402 | `plan_limit` |
| 403 | `forbidden`, `scope_required` |
| 404 | `not_found` |
| 409 | `conflict` |
| 413 | `payload_too_large`: over 1 MiB; use `/v1/uploads` |
| 429 | `rate_limited`, `workspace_busy` |
| 500 | `internal` |

## Lists

Arrays name their contents: `artifacts`, `responses`, `entries`. Data pagination returns
`cursor.next`; send `?cursor=`. Collection entries use `?page=`.

## Retries

A `POST` with `Idempotency-Key` replays its first answer for 24 hours. Artifact/project deletion
requires `?confirm=` matching its id.

## Polling and fair use

**Cache configuration in my workflow**

```prompt
Make my workflow cache its configuration in the runner. Share one fetch across the workflow group, refresh on an interval with jitter, and never poll faster than the config changes. Save the ETag and send If-None-Match on refresh. Honour Retry-After with backoff and keep the last-known-good configuration when a refresh fails.
```

Edge budgets per key: **600 reads/minute**, **120 writes/minute**, **20 email calls/hour**.
Workspace collection reads: **60/minute per collection per caller account**, shared across keys.
Artifact collection reads: **60/minute per collection per token holder within the artifact**;
collection writes: **30/minute per holder**. Response writes: **30/minute per token**,
**600/hour per artifact**, **120/hour per source address**. See [Limits](https://pr-1916-stg.superartifacts.app/docs/reference/limits.md).

Collection reads return `ETag`; send `If-None-Match` for an unchanged page's `304`.
Both responses use `Cache-Control: private, no-cache`. Authorization and budgets still apply.
Cache config in your runner; share one fetch per workflow group. Refresh with jitter,
never faster than config changes. Honour `Retry-After` seconds with backoff; keep last-known-good.
Over-budget calls get `429`; continued polling meets existing key/endpoint throttles.

## Every MCP tool has an endpoint

| MCP tool | Endpoints |
| --- | --- |
| `super_whoami` | GET /v1/whoami |
| `super_publish` | POST /v1/artifacts |
| `super_upload` | POST /v1/uploads |
| `super_artifacts` | GET /v1/artifacts, GET /v1/artifacts/{artifact}, GET /v1/artifacts/{artifact}/file, POST /v1/artifacts/{artifact}/open |
| `super_artifact_set` | PATCH /v1/artifacts/{artifact}, DELETE /v1/artifacts/{artifact}, POST /v1/artifacts/{artifact}/versions/{version}/serve, POST /v1/artifacts/{artifact}/live, DELETE /v1/artifacts/{artifact}/live |
| `super_data` | GET /v1/artifacts/{artifact}/data, GET /v1/data |
| `super_data_query` | POST /v1/data/query |
| `super_data_write` | POST /v1/artifacts/{artifact}/data/rows |
| `super_data_schema` | GET /v1/schema, PUT /v1/schema |
| `super_entries` | GET /v1/collections/{collection}/entries, POST /v1/collections/{collection}/entries |
| `super_secret_use` | POST /v1/collections/{collection}/entries/{entry}/fields/{field}/use |
| `super_templates` | GET /v1/templates, GET /v1/templates/{slug}, GET /v1/templates/{slug}/history, GET /v1/templates/{slug}/feedback |
| `super_template_save` | POST /v1/templates |
| `super_template_action` | POST /v1/templates/{slug}/actions |
| `super_release_template` | POST /v1/templates/{slug}/release |
| `super_project` | GET /v1/projects, POST /v1/projects, GET /v1/projects/{project}, PATCH /v1/projects/{project}, DELETE /v1/projects/{project}, POST /v1/projects/{project}/artifacts, DELETE /v1/projects/{project}/artifacts/{remove} |
| `super_share` | POST /v1/artifacts/{artifact}/shares, POST /v1/projects/{project}/shares, POST /v1/workspace/shares |
| `super_comments` | GET /v1/artifacts/{artifact}/comments, POST /v1/artifacts/{artifact}/comments/responses, GET /v1/artifacts/{artifact}/comments/screenshots/{screenshot}, GET /v1/mentions |
| `super_signatures` | GET /v1/signatures, POST /v1/signatures, GET /v1/signatures/{request}, POST /v1/signatures/{request}/remind, POST /v1/signatures/{request}/withdraw |
| `super_help` | GET /v1/help |