Developers
Shelf API: a guide for integrations and agents
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/v1carriesAPI-Version: 1.
Authenticate
Pick the credential that fits:
| Credential | How | Access |
|---|---|---|
| MCP connection | The hosted MCP (https://shelf.tri2b.cloud/mcp) with OAuth sign-in: the person names the connection and picks its permissions on Shelf's consent step | Only the capability scopes the person allowed; disconnected at once from Settings → MCP connections. The right choice for an AI assistant. |
| OIDC access token | Authorization: Bearer <JWT> from Shelf's identity provider (mobile app, shelf-mcp login) | Full access |
| Session cookie | shelf_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:
| Route | Paging |
|---|---|
GET /audit, GET /evidence | limit + cursor (the previous page's next_cursor; null at the end) |
GET /filing/candidates | limit + after (the previous page's next_after) |
GET /search | page (from 1) + per_page (1-50) |
GET /files/processing | limit, with truncated: true when there are more |
GET /shelves/{id}/files | Opt-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-connections | status (active or revoked), limit (1-100, default 50) and cursor; the body is {"connections": [...], "next_cursor": ..., "active_count": n} |
GET /files | Opt-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 link | limit (1-200, default 50) + cursor (the previous page's next_cursor) |
GET /webhooks/{id}/deliveries | limit + 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 10404s an address is refused until the oldest of those404s 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
429rate_limitedwithRetry-After. - Plan limits (storage, documents, credits) are
402plan_limitand not retryable; the body'sreasonsays which andupgrade_urlwhere 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.
| Call | Answers | Completion |
|---|---|---|
POST /files, POST /files/import/google-drive | 201 once the file is stored, processing.status queued | processing.next_action leaves wait; webhooks document.processing_succeeded / document.processing_failed |
POST /files/{id}/parse (alias /analyze) | 202 with the processing state | As above, for the new reading (generation + 1) |
POST /parsers/drafts | 202 with the draft | GET /parsers/drafts/{id} until it is ready (actions answer 409 not_ready meanwhile) |
POST /parsers/{id}/reread | 202 with the run | GET /parsers/{id}/reread until run.status is done; changed documents fire document.analyzed |
POST /changesets/{id}/apply of a reparse changeset | 200 with each item applied once its reading is queued | As for POST /files/{id}/parse, per document (GET /files/processing?ids=…) |
POST /webhooks/{id}/test, …/redeliver | 202 with the queued delivery | GET /webhooks/{id}/deliveries |
| Webhook deliveries | n/a | At 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:
| Effect | Means | Examples |
|---|---|---|
read | Changes nothing | Every GET; POST /changesets and POST /filing/plan (previews); POST /parsers/validate |
create / update | Adds or changes; undo by changing back | Upload, rename, move, edit text, create a share link |
action | Starts work or sends something | Re-read, apply a changeset, test a webhook, test a parser candidate, apply a parser to documents |
delete_reversible | To the trash, restorable for 30 days | DELETE /files/{id}, /folders/{id}, /shelves/{id} |
delete_permanent | Cannot be undone | Purge 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(orGET /files/processing?ids=a,b,cfor a batch) every few seconds untilprocessing.next_actionis notwait. - Subscribe a webhook to
document.processing_succeededanddocument.processing_failed(beta), and fetch the document when it fires.
Then act on next_action:
next_action | Meaning | Do |
|---|---|---|
none | Read; result complete or no_text | Use the document |
review | Only when the api setting REVIEW_ENABLED is on (default off): read, but the parser's result is incomplete; stages.parser.problems says what's missing | Use parse_result with care, or review it (POST /files/{id}/review) |
retry | Failed for a reason that may pass | POST /files/{id}/parse later |
report | Failed 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
409withstaleand 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'sstatusisapplied,partialorfailed. - A changeset applies once, within the hour it lives. A retry with the same
Idempotency-Keygets the first answer. - Operations:
file.update(documents:write),file.delete(documents:delete),folder.deleteandshelf.delete(shelves:delete),reparse(documents:write). Deletes go to the trash. At most 500 items. reparsereads many documents again (items are{"id": …}only). Applying queues one reading perreadyitem 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 isinvalidwith codeplan_limit. A document already queued isunchanged(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:
- Verify
v1= HMAC-SHA256 of"<t>.<raw body>"keyed with the secret, compared in constant time; reject an oldt(more than 5 minutes). - Drop events whose
idyou've already handled: delivery is at least once. - Don't rely on order: compare
created_atanddata.document.processing.generation, or treat the event as a cue andGET /files/{id}. - Answer
2xxwithin 15 seconds; anything else is retried (30 s up to 12 h, then failed).POST /webhooks/{id}/deliveries/{deliveryId}/redeliversends 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
422withdiagnosticson submit and replace;validateanswers200with the same diagnostics. - Activation is
409if the current version isn't tested, ifversionisn't the current one, or (for a revision) if the parser has moved pastbase_revision: submit a new candidate from its current spec. applyskips documents of another kind, not read yet, or edited by hand (reason_code), and firesdocument.analyzedfor each it changes.POST /parsers/{id}/rereadreads everything the parser already reads, in the background.GET /parsers/{id}/revisionslists 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:
- A change to the router, a route's scope (
internal/httpx/scopes.go) or itsIdempotency-Keysupport (internal/httpx/idempotency.go) must updateopenapi.yaml, orgo test ./internal/httpxfails (TestOpenAPI_CoversRouternames the route and what differs). - 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. - Bump
info.version(minor for additions, patch for wording). TestOpenAPI_ValidOpenAPI31validates the file against the OpenAPI Initiative's 3.1 schemas (vendored ininternal/httpx/testdata), andTestOpenAPI_WellFormedchecks every$ref, path parameter andoperationId.
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).