REST API

Everything your agent does over MCP is also an HTTPS endpoint, for code with no MCP client: a script, a scheduled job, your own backend. API endpoints 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 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 lists every one.

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

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.

Every MCP tool has an endpoint