# 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.237.0 · Next: [API endpoints](https://pr-2197-stg.superartifacts.app/docs/reference/api-endpoints.md)

Solo and higher include REST API and SDK access. The paid-plan gate is currently in shadow mode: it records unpaid calls without refusing them. MCP and skills stay free.

The [MCP operations](https://pr-2197-stg.superartifacts.app/docs/reference/mcp.md) have versioned HTTPS endpoints. For stored secrets, use the [MCP approval flow](https://pr-2197-stg.superartifacts.app/docs/secrets.md). See [API endpoints](https://pr-2197-stg.superartifacts.app/docs/reference/api-endpoints.md)
for operations, or use an [SDK](https://pr-2197-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-2197-stg.superartifacts.app/docs/reference/errors.md) lists stable codes.

| Status | `code` |
| --- | --- |
| 400 | `invalid_arguments`, `invalid_*` |
| 401 | `unauthorized` |
| 402 | `plan_limit`, `plan_required` |
| 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 a recorded answer for 24 hours. Server errors and `429` are not recorded. Reusing the key with different request bytes returns `409 idempotency_conflict`. Artifact/project deletion
requires `?confirm=` matching its id.

<a id="rate-limits" />

## 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-2197-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 configuration and share a fetch per workflow group. Honour `Retry-After` seconds with backoff.

## Operations

| 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, POST /v1/artifacts/{artifact}/comments/reactions, POST /v1/artifacts/{artifact}/comments/resolutions, 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_webhooks` | GET /v1/webhooks, POST /v1/webhooks, GET /v1/webhooks/{id}, DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/test, POST /v1/webhooks/{id}/rotate, GET /v1/webhook-messages |
| `super_help` | GET /v1/help |

A listed operation describes the API surface, not a guarantee that every credential can call it. See [permissions and keys](https://pr-2197-stg.superartifacts.app/docs/agents.md).
