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.
reference~3 minVerified v0.237.0
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 have versioned HTTPS endpoints. For stored secrets, use the MCP approval flow. See API endpoints for operations, or use an SDK.
Base URL and key
Send JSON to https://superartifacts.app/v1. Create a key in
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 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.
Polling and fair use
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.
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.