REST API

Every MCP tool has an HTTPS endpoint. 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.

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

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