REST API

The REST API and SDKs need a Solo plan or higher. MCP and skills are unaffected.

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