REST API

Base URL and format

https://incantory.ai/api/v1

Requests and responses are JSON (Content-Type: application/json) unless an endpoint says otherwise; /raw returns text/plain and /download returns an archive. Timestamps are ISO 8601 in UTC.

The machine-readable description is the OpenAPI 3.1 document at /api/v1/openapi.json. It is generated from the same schemas the server validates requests with, so it cannot drift from the implementation. Point an API explorer or a client generator at it.

Authentication

Send an API token as a bearer token:

GET /api/v1/prompts/alice/code-review HTTP/1.1
Host: incantory.ai
Authorization: Bearer inc_...

Create tokens at Settings → Security. Scopes cap what a token can do, whatever your account may do on the site:

Endpoints marked "optional" auth work anonymously and show more with a token; "required" answers 401 without one and 403 token_scope when the token lacks the scope. Some actions are never allowed to any token (minting tokens, changing sign-in methods, hard deletes).

Errors

Every error has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid request body",
    "details": [{ "path": "version", "code": "invalid_type", "message": "Expected number" }],
    "requestId": "5f0c1c9e-..."
  }
}

code is stable and meant for programs; message is for people. Quote the requestId (also in the X-Request-Id response header) when reporting a problem. The full list of codes is in Rate limits and errors.

Caching with ETags

Most GET responses carry an ETag. Send it back in If-None-Match and an unchanged resource answers 304 Not Modified with no body. Pinned versions (/versions/{n}) are immutable and cached for a year; polling a label with If-None-Match is the cheap way to notice a release.

curl -i -H 'If-None-Match: "abc123"' https://incantory.ai/api/v1/prompts/alice/code-review/labels

Pagination

Lists use keyset cursors, never page numbers. A response carries nextCursor; pass it back as cursor to get the next page. null means there are no more. Treat cursors as opaque strings: their contents may change, and a malformed one answers 400 invalid_cursor.

curl "https://incantory.ai/api/v1/prompts?kind=skill&limit=50"
curl "https://incantory.ai/api/v1/prompts?kind=skill&limit=50&cursor=eyJ..."

Rate limits

Requests are limited per token and per IP. See Rate limits and errors for the headers and how the SDKs retry.

Endpoints