# 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://superartifacts.app/docs/reference/api-endpoints.md)

Everything your agent does over [MCP](https://superartifacts.app/docs/reference/mcp.md) is also an HTTPS endpoint, for code
with no MCP client: a script, a scheduled job, your own backend. [API endpoints](https://superartifacts.app/docs/reference/api-endpoints.md)
lists every one, with a request you can build and copy.

## Base URL and key

Requests go to `https://superartifacts.app/v1`, with JSON bodies. Create a key in
[Settings → API keys](https://superartifacts.app/settings/api-keys) and send it on every request
as `Authorization: Bearer <key>`. The OpenAPI 3.1 document is
`https://superartifacts.app/v1/openapi.json`, public, for a client generator.

A key can **read**, or **read and write**. A read key that calls a write gets `403
scope_required`. Keys made before scopes existed can do both.

Keep the key on a server. A request carrying an `Origin` header, which every browser adds, is
refused with `403`.

## Errors

A failure has a status and one shape. `code` is stable; [Error codes](https://superartifacts.app/docs/reference/errors.md)
lists every one.

```json
{ "error": { "code": "not_found", "message": "No artifact with that id." } }
```

| Status | `code` |
| --- | --- |
| 400 | `invalid_arguments` and the other `invalid_*` codes |
| 401 | `unauthorized`: no key, or one that was revoked |
| 402 | `plan_limit` |
| 403 | `forbidden`, `scope_required` |
| 404 | `not_found` |
| 409 | `conflict` |
| 413 | `payload_too_large`: over 1 MiB; stage large files through `/v1/uploads` |
| 429 | `rate_limited`, `workspace_busy` |
| 500 | `internal` |

## Lists

A list answers an object whose array is named for what it holds: `artifacts`, `responses`,
`threads`, `entries`, `projects`, `templates`. Paged reads say how to get the next page
inside the answer: data reads return `cursor.next`, which you send back as `?cursor=`, and
collection entries take `?page=`. Each operation's page parameters are in its entry below.

## Retries

A `POST` sent with an `Idempotency-Key` header happens once: the same key within 24 hours
returns the first answer instead of doing it again. Deleting an artifact or a project needs
`?confirm=` set to its id.

## Rate limits

Per key: 600 reads a minute, 120 writes a minute, and 20 an hour to the endpoints that send
email (sharing and signature requests). Over a limit answers `429` with a `Retry-After` header
in seconds. The rest are in [Limits](https://superartifacts.app/docs/reference/limits.md).

## 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 |