Developers

Shelf API: a guide for integrations and agents

From the api repo’s docs/api.md at 509805b

The OpenAPI 3.1 spec (version 1.0.0) is at /docs/api/openapi.yaml: every route under /api/v1, its scope, request and response shapes, errors and webhook payloads. Agents connect over MCP instead: see the MCP server.

The Integration API is the spec’s /integration routes (tag Integrations): another platform reads, and with a read-and-manage key organises, one folder’s documents with a folder integration key, made under /folders/{id}/integrations. MCP connections and their scopes are at /docs/mcp/scopes.

Where this page cites “the README” it means the api repo’s README, which is not published; the routes it describes are all in the OpenAPI spec.

This is the working guide to Shelf's HTTP API. The machine-readable contract is openapi.yaml (OpenAPI 3.1): every route under /api/v1, its scope, request and response shapes, errors, and the webhook payloads. The README's "API" section is the long-form reference for each area; agent-scopes.md covers capability scopes and MCP connections, and mcp.md the MCP server, which wraps this API for AI assistants.

  • Base URL: https://app.shelf.tri2b.cloud/api/v1 (local stack: http://localhost:18080/api/v1).
  • JSON in, JSON out, except uploads (multipart), parser YAML, and the streamed files, previews and zips.
  • Every response under /api/v1 carries API-Version: 1.

Authenticate

Pick the credential that fits:

CredentialHowAccess
MCP connectionThe hosted MCP (https://shelf.tri2b.cloud/mcp) with OAuth sign-in: the person names the connection and picks its permissions on Shelf's consent stepOnly the capability scopes the person allowed; disconnected at once from Settings → MCP connections. The right choice for an AI assistant.
OIDC access tokenAuthorization: Bearer <JWT> from Shelf's identity provider (mobile app, shelf-mcp login)Full access
Session cookieshelf_session, set by browser sign-in at /auth/login; writes also need X-Shelf-CSRF: 1 and, if an Origin header is sent, one matching the app (otherwise 403 forbidden)Full access (the web app)

Agent keys (shelf_ak_…) are retired: one answers 401 with a message saying to connect with OAuth sign-in instead.

A connection's tokens are bearers like any other, minted by the MCP's OAuth proxy; with one, the agent can check what it may do:

export SHELF=https://app.shelf.tri2b.cloud/api/v1
export TOKEN=...               # a bearer; never log or commit it

curl -s "$SHELF/credential" -H "Authorization: Bearer $TOKEN"
# {"subject":"…","full_access":false,"scopes":["documents:read","shelves:read"],
#  "credential":{"kind":"mcp_connection","id":"…","name":"Research assistant","client_id":"…"}}

GET /credential is the cheapest way to check a credential works and see what it may do. Each operation in the spec names the scope it needs in x-shelf-scope:

  • a capability scope (documents:read, shelves:delete, …): a limited connection needs it;
  • any: any credential (changesets check the scope of the change itself);
  • full_access: only the person, signed in themselves. No connection can manage connections or billing, or purge from the trash;
  • none: no credential; the token in the path is the capability;
  • integration: only a folder integration key (see the README, "Integrations").

Without the scope: 403, code insufficient_scope, and required_scope names it. Ask the person to connect again and allow it; retrying won't help. 401 means the credential is missing, expired or revoked.

Every query is scoped to the person. Anything that isn't theirs answers 404, exactly as something that doesn't exist does.

Conventions

Errors and retrying

Every error is JSON:

{"error": "shelf_id must be a valid UUID", "code": "invalid_input",
 "message": "shelf_id must be a valid UUID", "retryable": false, "field": "shelf_id"}

Branch on code (the catalogue is #/components/schemas/ErrorCode; codes are only ever added). Retry only when retryable is true, after retry_after_seconds (also the Retry-After header), doubling the wait, at most 3 times. An unknown code falls back to its HTTP status: 429 and 5xx are retryable. A 500 after a write may have been applied: read the resource back before repeating it, or send the write with an Idempotency-Key so repeating it is safe.

Idempotency-Key

Creates and actions that take Idempotency-Key list it as a parameter in the spec (the drift test checks the list against the server). Send a fresh UUID per logical request and the same one on every retry: the first successful answer is replayed for 24 hours (with Idempotent-Replayed: true) and nothing runs twice. An answer over 1 MiB is not kept: the key is freed and a retry runs again. The same key with a different body is 422 idempotency_key_reused; while the first is still running, 409 idempotency_key_in_use (retry). PATCH, PUT, DELETE and GET set state rather than add to it and ignore the header.

Pagination

Lists are paged where they can be long, each in the way that suits it:

RoutePaging
GET /audit, GET /evidencelimit + cursor (the previous page's next_cursor; null at the end)
GET /filing/candidateslimit + after (the previous page's next_after)
GET /searchpage (from 1) + per_page (1-50)
GET /files/processinglimit, with truncated: true when there are more
GET /shelves/{id}/filesOpt-in: with folder_id (a folder's UUID, or root for the top level), limit (1-200, default 50) or cursor (the previous page's next_cursor, for the same shelf and folder; null at the end) the body is {"files": [...], "next_cursor": ...}, newest first; without them, the whole shelf as a bare array. ids_only=true with folder_id (not with limit/cursor) gives {"ids": [...], "count": n}: every document id in that folder, unpaged, no download URLs
GET /mcp-connectionsstatus (active or revoked), limit (1-100, default 50) and cursor; the body is {"connections": [...], "next_cursor": ..., "active_count": n}
GET /filesOpt-in: with sort, order, limit (1-200, default 50) or cursor (the previous page's next_cursor, for the same sort and order) the body is {"files": [...], "next_cursor": ...}; without them, the whole list as a bare array
GET /public/shares/{token} and .../folders/{cid} for a folder linklimit (1-200, default 50) + cursor (the previous page's next_cursor)
GET /webhooks/{id}/deliverieslimit + cursor (the previous page's Next-Cursor response header, absent at the end; the body stays a bare array, newest first)
Other lists (/shelves, /shelves/{id}/folders, …)Not paged: the whole list

Rate limits

  • The token-keyed public routes (/public/shares/*, GET /downloads/{token}): 60 requests a minute per client address, and after 10 404s an address is refused until the oldest of those 404s is a minute old. /public/shares/* also allows 300 a minute per share token; GET /downloads/{token} has only the per-address limits.
  • Born-digital uploads (read without OCR): 60 an hour per person.
  • Both answer 429 rate_limited with Retry-After.
  • Plan limits (storage, documents, credits) are 402 plan_limit and not retryable; the body's reason says which and upgrade_url where to go.

Beta interfaces

Operations marked x-shelf-beta: true (parsers and webhooks) may still change. They sit behind a per-person feature flag: with it off they answer 404 as if they didn't exist. Making a parser (importing one, drafting one or saving a new one in the studio) needs the Parsers plugin whether or not billing is on, and answers 402 parsers without it; other changes to parsers and webhooks need their plugin only with billing on. Reading them stays open. Everything else in v1 is stable under the compatibility rules in "Versioning" below.

Synchronous and asynchronous

Most calls finish their work before they answer. These don't: the answer says the work is accepted, and completion comes later.

CallAnswersCompletion
POST /files, POST /files/import/google-drive201 once the file is stored, processing.status queuedprocessing.next_action leaves wait; webhooks document.processing_succeeded / document.processing_failed
POST /files/{id}/parse (alias /analyze)202 with the processing stateAs above, for the new reading (generation + 1)
POST /parsers/drafts202 with the draftGET /parsers/drafts/{id} until it is ready (actions answer 409 not_ready meanwhile)
POST /parsers/{id}/reread202 with the runGET /parsers/{id}/reread until run.status is done; changed documents fire document.analyzed
POST /changesets/{id}/apply of a reparse changeset200 with each item applied once its reading is queuedAs for POST /files/{id}/parse, per document (GET /files/processing?ids=…)
POST /webhooks/{id}/test, …/redeliver202 with the queued deliveryGET /webhooks/{id}/deliveries
Webhook deliveriesn/aAt least once, unordered, retried for about a day

Search (GET /search) is indexed in the background: a new document is findable by its name shortly after upload, and by its text once it has been read. GET /evidence reads the database and is current. GET /files/{id} and the shelf, folder and file-list reads may come from a per-owner cache of up to 30 seconds (marked Shelf-Cache: hit) that every write by that owner invalidates.

Two parser calls that might look like background work are synchronous: POST /parsers/candidates/{id}/test (up to 50 documents) and POST /parsers/{id}/apply (up to 100) answer with every document's outcome. They read the text Shelf already has and never call Vision.

Destructive and reversible

Each operation's x-shelf-effect says what it does:

EffectMeansExamples
readChanges nothingEvery GET; POST /changesets and POST /filing/plan (previews); POST /parsers/validate
create / updateAdds or changes; undo by changing backUpload, rename, move, edit text, create a share link
actionStarts work or sends somethingRe-read, apply a changeset, test a webhook, test a parser candidate, apply a parser to documents
delete_reversibleTo the trash, restorable for 30 daysDELETE /files/{id}, /folders/{id}, /shelves/{id}
delete_permanentCannot be undonePurge from the trash (person only), revoke a share link, disconnect an MCP connection, delete a parser, parser candidate or webhook

Two things to know before deleting:

  • Deleting a folder or shelf takes everything under it to the trash with it; restoring it (POST …/{id}/restore) brings back exactly that.
  • Processing a document again replaces a hand edit of its text with what Shelf reads.

For anything touching many documents, or a judgement call about someone's files, preview a changeset and apply it only after the person agrees (below).

Workflows

1. Find documents

# Full-text search (filenames, folder and shelf names, labels, parser fields, text)
curl -s "$SHELF/search?q=electricity+invoice&category=documents&per_page=10" \
  -H "Authorization: Bearer $TOKEN"

Each hit has id, name, shelf, folder_path and a snippet. Read one in full with GET /files/{id} (parsed_text, parse_result, processing).

To answer a question across many documents ("what did we pay Acme this year?"), ask for evidence instead of downloading each one:

curl -s -G "$SHELF/evidence" -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'where=Supplier~acme' --data-urlencode 'uploaded_from=2026-01-01' \
  --data-urlencode 'aggregate=Total' --data-urlencode 'limit=0'

Every value comes with the document_id and origin it came from. If partial is true, partial_reasons says what the answer may be missing (more pages, unread documents, unreviewed values).

Needs documents:read.

2. Upload a document and wait for it to be read

SHELF_ID=$(curl -s "$SHELF/shelves" -H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')

curl -s "$SHELF/files" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F file=@invoice.pdf -F shelf_id="$SHELF_ID"
# 201 {"id":"…","parse_status":"pending","processing":{"status":"queued","next_action":"wait",…}}
# 200 {"id":"…","duplicate":true,…}   when these exact bytes are already on a shelf

Then wait, either way:

  • Poll GET /files/{id}/processing (or GET /files/processing?ids=a,b,c for a batch) every few seconds until processing.next_action is not wait.
  • Subscribe a webhook to document.processing_succeeded and document.processing_failed (beta), and fetch the document when it fires.

Then act on next_action:

next_actionMeaningDo
noneRead; result complete or no_textUse the document
reviewOnly when the api setting REVIEW_ENABLED is on (default off): read, but the parser's result is incomplete; stages.parser.problems says what's missingUse parse_result with care, or review it (POST /files/{id}/review)
retryFailed for a reason that may passPOST /files/{id}/parse later
reportFailed because of the file (password, damaged, unsupported)Tell the person; reading it again won't help

With review off, a reading that fails its checks is stored as parsed with its problems recorded, and no review is offered (next_action is none).

From Google Drive, POST /files/import/google-drive takes the Picker's file_id and short-lived access_token instead of a multipart file, and answers like an upload. Before importing, ask which of the picked files were imported before, so the person can be warned rather than get a second copy by surprise:

curl -s "$SHELF/files/import/google-drive?ids=1AbC…,1XyZ…" -H "Authorization: Bearer $TOKEN"
# 200 {"imports":[{"file_id":"1AbC…","previous_imports":[{"id":"…","exported_at":"…","source_modified_at":"…",…}]},
#                 {"file_id":"1XyZ…","previous_imports":[]}]}

It reads only the caller's files (no Google call, no token). The Drive file changed since if the Picker's lastEditedUtc is later than the newest import's source_modified_at.

Needs documents:upload (and documents:read to poll or check Drive imports).

3. Organise with a changeset

Never move or delete many documents one call at a time. Preview, show the person, then apply:

curl -s "$SHELF/changesets" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{
  "operation": "file.update",
  "items": [
    {"id": "<file-1>", "folder_id": "<invoices-folder>"},
    {"id": "<file-2>", "filename": "2026-09 Electricity.pdf"}
  ]}'
# 201 {"id":"<cs>","status":"previewed","expires_at":"…","summary":{"ready":2},
#      "items":[{"index":0,"status":"ready","before":{…},"after":{…},"changes":{…}},…],
#      "next":"Nothing has changed yet. Show the person the items …"}

Nothing has changed yet. Show the person items (each before, after, changes; items that can't be done say why in status and reason). Once they agree:

curl -s -X POST "$SHELF/changesets/<cs>/apply" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
# 200 {"status":"applied", "items":[{"index":0,"result":{"status":"applied"}},…]}
  • Apply re-checks every item. If anything changed since the preview, it answers 409 with stale and changes nothing: preview again and show the new one.
  • Items are applied one at a time, not all-or-nothing: read each item's result (applied, skipped, stale, failed); the changeset's status is applied, partial or failed.
  • A changeset applies once, within the hour it lives. A retry with the same Idempotency-Key gets the first answer.
  • Operations: file.update (documents:write), file.delete (documents:delete), folder.delete and shelf.delete (shelves:delete), reparse (documents:write). Deletes go to the trash. At most 500 items.
  • reparse reads many documents again (items are {"id": …} only). Applying queues one reading per ready item and returns; the readings run in the background (see "Synchronous and asynchronous"). Plan limits are checked once for the batch: while the account is over them, every item that would be read is invalid with code plan_limit. A document already queued is unchanged (not_ready), so previewing and applying the same set again queues nothing more. Reading again replaces a hand edit of the text.

Filing is the same with the classifying done for you to check: GET /filing/candidates (unfiled documents and what Shelf read of them), GET /filing/destinations (every folder, by path), then POST /filing/plan with a decision and confidence per document. The sure ones become a previewed file.update changeset (id), applied as above; the rest stay where they are with an outcome saying why.

4. Consume results

Pull. GET /files/{id} is the authoritative state: parsed_text (with the parser's corrections), parse_result (fields and rows a parser read), parser_name, vision_labels, content_html and processing. Download the original from download_url (signed, 15 minutes).

Push (beta). Register a webhook for the events you want:

curl -s "$SHELF/webhooks" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" -d '{
  "url": "https://example.com/shelf-hook",
  "events": ["document.processing_succeeded", "document.processing_failed", "document.edited"],
  "shelf_id": "<shelf>", "include_content": true}'
# 201 {…, "secret": "…"}   shown once: store it

Each delivery is a POST of a WebhookEvent (see the spec's webhooks section) with Shelf-Event, Shelf-Event-Id, Shelf-Delivery (this delivery's id; it differs on each redelivery) and Shelf-Signature: t=<unix>,v1=<hex> headers. On receipt:

  1. Verify v1 = HMAC-SHA256 of "<t>.<raw body>" keyed with the secret, compared in constant time; reject an old t (more than 5 minutes).
  2. Drop events whose id you've already handled: delivery is at least once.
  3. Don't rely on order: compare created_at and data.document.processing.generation, or treat the event as a cue and GET /files/{id}.
  4. Answer 2xx within 15 seconds; anything else is retried (30 s up to 12 h, then failed). POST /webhooks/{id}/deliveries/{deliveryId}/redeliver sends one again.

Needs webhooks:write to register, documents:read to pull.

5. Write a parser (beta)

An agent writes a parser as a candidate, which reads nothing until it is activated. Testing and activating change no document; reading documents with it is its own step.

# The format, with an example per way of reading
curl -s "$SHELF/parsers/schema" -H "Authorization: Bearer $TOKEN"

# Check a draft spec; nothing is saved
curl -s "$SHELF/parsers/validate" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "$(jq -n --rawfile s acme.parser.yaml '{spec:$s}')"
# 200 {"valid":false,"parser":null,"diagnostics":[{"severity":"error","code":"schema","path":"fields[1].type","line":14,"message":"…"}]}

# Submit it (add "parser_id" to revise an existing parser instead)
curl -s "$SHELF/parsers/candidates" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' \
  -d "$(jq -n --rawfile s acme.parser.yaml '{spec:$s}')"
# 201 {"id":"<cand>","status":"candidate","version":1,"tested":false,"warnings":[…],…}

# Test it against documents the person already has
curl -s "$SHELF/parsers/candidates/<cand>/test" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"file_ids":["<file-1>","<file-2>"]}'
# 200 {"version":1,"summary":{"documents":2,"valid":2,"changed":1,…},
#      "documents":[{"file_id":"…","outcome":"valid","result":{…},"current":{…},"diff":{…}},…],
#      "fields":[{"name":"Total","found":2,"read":2},…]}

Revise with PUT /parsers/candidates/{id} (the next version, to be tested again) until the test says what you want, show the person the diff, then activate the version you tested:

curl -s -X POST "$SHELF/parsers/candidates/<cand>/activate" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"version":1}'
# 201 {"candidate":{…,"status":"activated"},"parser":{"id":"<parser>",…}}   (200 for a revision)

# Read chosen documents with it now (synchronous)
curl -s "$SHELF/parsers/<parser>/apply" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{"file_ids":["<file-1>","<file-2>"]}'
# 200 {"changed":1,"unchanged":1,"skipped":0,"failed":0,"documents":[…]}
  • A spec that isn't a valid parser is 422 with diagnostics on submit and replace; validate answers 200 with the same diagnostics.
  • Activation is 409 if the current version isn't tested, if version isn't the current one, or (for a revision) if the parser has moved past base_revision: submit a new candidate from its current spec.
  • apply skips documents of another kind, not read yet, or edited by hand (reason_code), and fires document.analyzed for each it changes. POST /parsers/{id}/reread reads everything the parser already reads, in the background.
  • GET /parsers/{id}/revisions lists every revision with the candidate that made it.

Needs parsers:read (schema, validate, list), parsers:write (submit, replace, discard, test, activate) and parsers:execute (apply). A new parser needs the Parsers plugin whether or not billing is on (402 parsers without it).

Versioning and keeping this up to date

The API. The path carries the major version (/api/v1) and every response says API-Version: 1. Within v1, changes are additive only: new routes, new optional request fields, new response fields, new error codes, new webhook events (a webhook only receives events listed in its events). Nothing is renamed, removed, retyped or moved to another status. A breaking change is served at /api/v2 alongside v1. Webhook bodies carry their own schema_version. Clients should ignore fields they don't know.

Beta operations (x-shelf-beta) may change shape before they leave beta; the change is noted in the release that makes it.

The spec. info.version in openapi.yaml is the document's own semver: major = the API's path version, minor = something added (a route, a field, an event, a code), patch = wording and examples. It changes in the same pull request as the code it describes:

  1. A change to the router, a route's scope (internal/httpx/scopes.go) or its Idempotency-Key support (internal/httpx/idempotency.go) must update openapi.yaml, or go test ./internal/httpx fails (TestOpenAPI_CoversRouter names the route and what differs).
  2. A change to a request or response shape, an error code, or a webhook event updates the matching schema in openapi.yaml, the README section, and this guide if a workflow changes. These aren't machine-checked yet: reviewers check them.
  3. Bump info.version (minor for additions, patch for wording).
  4. TestOpenAPI_ValidOpenAPI31 validates the file against the OpenAPI Initiative's 3.1 schemas (vendored in internal/httpx/testdata), and TestOpenAPI_WellFormed checks every $ref, path parameter and operationId.

The spec covers /api/v1 only. /healthz, /version and the browser sign-in routes under /auth are infrastructure, outside the API contract, and the mock billing routes exist only in local development (PADDLE_ENVIRONMENT=mock).