Barrel
FR GitHub

REST API

This is the list of every route barrel_server serves, with who may call it, what to send and what comes back. Use it when you write a client by hand or check what a route does; the server guide shows the same routes in a worked session. It is built from the route table in barrel_server_api.erl (barrel_server 1.14.0), and the example answers were captured from a running server.

Check the details

The OpenAPI file at /openapi.yaml lists every route this page lists, and a barrel test fails when the two differ. Some request and response details still differ from the server, so check this page before you generate a client from it.

Known differences: it says GET / is public, but it needs auth when auth is configured; it returns {id, _rev} from PUT /db/:db/doc/:id, the server returns {id, ok, rev}; it types /find where items as objects, they are arrays such as ["path",["kind"],"note"], and it allows extra keys the server refuses; it omits max_rows, deadline_ms, ?conflicts=true, the write headers, and the 501, 503 and 500 attachment and search errors; the contexts and working-set routes are listed with loose bodies.

Conventions

  • Bodies are JSON unless a route says otherwise. Errors are {"error": "<code>"}; see Error codes.
  • Only PUT /db/:db creates a database. Every other /db/:db/... route answers 404 {"error":"db_not_found"} when the database does not exist.
  • Names use lowercase letters, digits, _ and -, 1 to 63 bytes, and must not start with _; any other name answers 400 invalid_name. The internal _barrel_system database is not reachable over REST.
  • Revisions look like 000001a1b876972d00000000@w78160d59891ba7d7. Send the current one as _rev to update.
  • Writes accept x-barrel-actor, x-barrel-session and x-barrel-source headers, recorded as provenance (256 bytes each).
  • Changes cursors are URL-safe base64 HLCs such as AAABobh2tYwAAAAB.

Auth classes

ClassWho passes
publicAnyone, even when auth is configured
serverA server bearer token, a signed request or mTLS
read, writeA server credential, or a capability token with that right when :db is its space
agentA live capability token; the handler then checks its rights
server onlyA server credential; capability tokens get 403

A server with no auth configured skips every check. See Authentication.

Meta

RouteAuthRequestResponseErrors
GET /servernone200 text barrel edge database401
GET /healthpublicnone200 {"status":"ok"}; checks no databasenone
GET /readypublicnone200 {"status":"ready"} when the database and replication processes run503 {"status":"not_ready","failed":[...]}, failed among databases, stores, replication

Databases

RouteAuthRequestResponseErrors
PUT /db/:dbserver onlyoptional {"att_opts":{"backend":"blob"|"s3","s3":{...}}}201 {"ok":true,"db":"demo"}400 invalid_name, bad_att_opts
GET /db/:dbreadnone200 info: name, config, read_only, db_path, keyspace, retention_period, history_floor, att_floor, write_groups, embedder400, 500
DELETE /db/:dbserver only?purge=true also deletes the files200 {"ok":true,"db":"demo"}, plus "purged":true500

Documents

RouteAuthRequestResponseErrors
PUT /db/:db/doc/:idwritethe document; _rev to update; provenance headers201 {"id","ok":true,"rev"}409 conflict, 400 bad_json, invalid_provenance
GET /db/:db/doc/:idread?include_embedding=true, ?conflicts=true (adds _conflicts, _observed)200 the document with _rev404 not_found
DELETE /db/:db/doc/:idwriteprovenance headers200 {"id","ok":true,"rev"}404
POST /db/:db/_bulk_docswrite{"docs":[...]}201 {"results":[{"id","ok","rev"} or {"error"}]}400
POST /db/:db/_bulk_getread{"ids":[...],"include_embedding"?}200 {"results":[doc or {"error":"not_found"}]}400
GET /db/:db/doc/:id/_versionsreadnone200 {"id","versions":[{rev,status,deleted,provenance?}]}404
GET /db/:db/doc/:id/_versions/:revreadnone200 the stored body of that version404
GET /db/:db/_historyread?since, ?until (cursors), ?limit, ?id200 {"history":[{id,rev,deleted,cause,hlc,provenance?}]}400 bad_since, bad_until, bad_limit
curl -X PUT localhost:8080/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"hello world","kind":"note"}'
{"id":"a","ok":true,
 "rev":"000001a1b876972d00000000@w78160d59891ba7d7"}

Find and query

RouteAuthRequestResponseErrors
POST /db/:db/findreadwhere, limit, offset, include_docs, id_prefix, continuation; any other key is refused200 {"rows":[{id,doc}],"meta":{has_more,continuation?}}400 invalid_query + reason
POST /db/:db/queryreadraw BQL with a non-JSON content type, or {query, params, continuation, max_rows, deadline_ms}200 application/x-ndjson: {"row":...} lines, then {"meta":{...}}400 invalid_query + message, line, column; missing_query; bad_json; invalid_max_rows; invalid_deadline_ms; subscribe_requires_sse
GET /db/:db/queryread?q=, ?max_rows=, ?deadline_ms= (for EventSource)as for POSTas for POST
  • where items are arrays in the replication-filter form, such as ["path",["kind"],"note"].
  • /find returns meta.continuation when there are more rows. To read the next page, send it back as continuation in the body with the same query; a malformed one answers 400 invalid_query. It returns doc in every row, with or without include_docs.
  • max_rows is at most 1000 and deadline_ms at most 300000. The final meta line carries has_more, bound (limit_reached or exhausted), count, continuation, instance_id, last_seq and, for search, embedding. An error after rows were sent arrives as a last line {"error":"deadline"} or another reason.
  • A SUBSCRIBE statement needs Accept: text/event-stream or ?feed=sse, and streams the events row, ready, change, error and ping (every 30 s).
curl -X POST localhost:8080/db/demo/query \
  -H 'content-type: text/plain' \
  --data-binary "SELECT id, title FROM c
    WHERE kind = 'note' ORDER BY id LIMIT 2"

The answer, captured with the same statement sent as JSON:

{"row":{"id":"a","title":"hello world"}}
{"row":{"id":"c","title":"third"}}
{"meta":{"count":2,"bound":"limit_reached",
 "last_seq":"AAABobh2tYwAAAAB",
 "instance_id":"95e252eeaff57fa0","has_more":false}}

Changes

RouteAuthRequestResponseErrors
GET /db/:db/changesread?since=<cursor> or first; ?feed=sse or continuous, or Accept: text/event-stream200 {"changes":[{id,rev,hlc,changes:[{rev}],num_conflicts}],"last":cursor}none

A bad since does not fail: the feed restarts from the first change. With SSE, a one-shot read sends data: lines then event: last; continuous keeps the stream open with a ping every 30 s.

Attachments

RouteAuthRequestResponseErrors
PUT /db/:db/doc/:id/att/:namewriteraw bytes; content-type; If-None-Match: * to create only; If-Match: <etag>201 {name,length,digest,content_type,chunked}; the document _rev does not change400 bad_if_none_match, 409 conflict, 501 conditional_writes_unsupported or attachments_disabled, 503 att_sync_pending
GET /db/:db/doc/:id/att/:namereadnone200 the bytes with their stored content type404
DELETE /db/:db/doc/:id/att/:namewritenone200 {"ok":true}404
RouteAuthRequestResponseErrors
POST /db/:db/vectorwrite{id, text, metadata, vector?}; without vector the server embeds text201 {"ok":true,"id"}500 dimension mismatch or no embedder
POST /db/:db/search/vectorread{"vector":[...],"k"}; k defaults to 10, at most 10000200 {"hits":[{key,score,text,metadata}]}500 {dimension_mismatch,768,N}
POST /db/:db/search/bm25read{"query","k"}200 {"hits":[{key,score}]}500 bm25_not_enabled
POST /db/:db/search/hybridread{"query","k"}200 {"hits":[...]}500 embedder_not_configured

A database opened with the default options has a 768-dimension cosine vector store, BM25 off and no embedder. Set open_opts in the server configuration, or open the database in record mode, to get keyword and hybrid search.

Timeline

All timeline routes are server only.

RouteRequestResponseErrors
GET /db/:db/_timelinenone{"db","branches":[...],"parent"?,"fork_hlc"?}400, 500
POST /db/:db/_timeline/branch{"name", "at"?} (a changes cursor) or {"name", "at_time"?} (RFC 3339)201 {"ok","branch","parent","fork_hlc"}400 invalid_name, bad_at, pitr_window_exceeded; 409 already_exists, cannot_branch_a_branch
POST /db/:db/_timeline/mergenone; call it on the branch200 docs_read, docs_written, failed, last_merged, att_sync409 not_a_branch, 404 parent_not_found

Replication wire

These routes carry replication between nodes and barrel-lite. You do not call them by hand; barrel_rep and barrel-lite do. Every response carries an x-barrel-hlc header. They never create a database.

RouteRightPurpose
GET /db/:db/_sync/inforeadCapabilities: full_state, att_flush, att_filter, floors
POST /db/:db/_sync/hlcreadClock exchange
POST /db/:db/_sync/changesread{since, limit, filter?, deleted?} to {changes, last_seq}
POST /db/:db/_sync/diffreadThe versions the server is missing
GET, PUT /db/:db/_sync/doc/:idread, writeOne version
GET, PUT /db/:db/_sync/state/:idread, writeThe whole document state
PUT /db/:db/_sync/repair/:idwriteRepair bodies, used by reconcile
GET, PUT, DELETE /db/:db/_sync/local/:idread, write, writeReplication checkpoints
GET /db/:db/_sync/att_changesreadAttachment feed
POST /db/:db/_sync/att_diffread{attachments, touch?}
POST /db/:db/_sync/att_listread{ids}
POST /db/:db/_sync/att_flushwriteMake attachment writes durable
GET /db/:db/_sync/att_state/:id/:namereadAttachment state
GET, PUT, DELETE /db/:db/_sync/att/:id/:nameread, write, writeStreamed attachment bytes, with x-barrel-digest, x-barrel-att-origin, x-barrel-att-touch

Spaces, sessions and handoffs

All agent class. See the spaces guide for the bodies.

RoutesPurpose
POST, GET /spaces; GET, DELETE /spaces/:spaceCreate, list, read and drop spaces
POST, GET /spaces/:space/grants; DELETE /spaces/:space/grants/:token_idIssue, list and revoke capability tokens
POST, GET /spaces/:space/sessions; GET, DELETE .../sessions/:sid; POST .../sessions/:sid/touchSessions with a sliding TTL
POST, GET .../sessions/:sid/messagesSession messages
PUT, GET .../sessions/:sid/data/:keySession data
POST, GET /handoffs; POST /handoffs/accept; POST /handoffs/completeHandoffs
curl -X POST localhost:8080/spaces \
  -H 'content-type: application/json' \
  -d '{"label":"team"}'
{"ok":true,"space":"sp_..."}

Contexts and working sets

See the contexts guide for the bodies.

RouteAuth
POST /contexts (201)server only
GET /contexts (?prefix=, ?unlisted=true, ?q=)agent
GET /contexts/_capabilitiesagent
GET /contexts/_offlineagent
PUT /contexts/_offlineserver only
POST /contexts/_queryagent; each local member is checked as POST /db/:db/query
GET /contexts/:idagent
DELETE /contexts/:idserver only
POST, GET /worksetsserver only
GET, DELETE /worksets/:wsserver only
POST /worksets/:ws/membersserver only
DELETE /worksets/:ws/members/:ctxserver only
POST /worksets/:ws/_materializeserver only
POST /worksets/:ws/_importserver only

There is no route to update a context card.

MCP

POST, GET, DELETE and OPTIONS /mcp serve the Model Context Protocol over streamable HTTP. It accepts bearer tokens only. The tools are listed in MCP tools.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open