Barrel
FR GitHub

Run the REST server

barrel_server exposes the barrel database as a REST/JSON API using livery. By default it serves cleartext HTTP/1.1; HTTP/2 and HTTP/3 (over TLS) are opt-in via the listeners config (see synchronization). It holds no database logic: every handler calls the barrel module through a database lifecycle manager. Read this when you want to reach a barrel database over the network instead of embedding it.

When to use it

  • You want HTTP access to documents, attachments, vectors, search, the changes feed, and contexts (from other languages or remote clients).
  • For in-process Erlang use, embed barrel directly instead (see the embedding guide).

Build and run

barrel_server is opt-in, behind the umbrella server profile (it pulls livery and its transports). It is not part of the default embeddable build.

$ rebar3 as server shell
1> application:ensure_all_started(barrel_server).

Configure with the barrel_server app env: http_port (default 8080) and data_dir (where databases are stored). Set them before the app starts, for example in sys.config.

To run the server without building it, use the Docker image (see the Docker guide).

Endpoints

Create a database with PUT /db/:db before you use it: every other /db/:db route answers 404 {"error":"db_not_found"} when the database does not exist, so a mistyped name never leaves an empty database behind. Names are lowercase letters, digits, _ and -, 1 to 63 bytes, not starting with _; others answer 400 invalid_name.

Existing databases open lazily on first use through Barrel's database lifecycle manager (barrel_dbs): handles are cached by name, idle databases close after dbs_idle_timeout (barrel app env, default 5 minutes, 0 disables), and dbs_max_open evicts the least recently used past a cap.

GET    /                          liveness text
GET    /health                    {"status":"ok"} when the listener answers
GET    /ready                     200 {"status":"ready"}, or 503 with the failed checks

PUT    /db/:db                     open/create a database
GET    /db/:db                     database info
DELETE /db/:db                     close a database (?purge=true deletes)

PUT    /db/:db/doc/:id             body = JSON document
GET    /db/:db/doc/:id             fetch a document
DELETE /db/:db/doc/:id             delete a document
POST   /db/:db/_bulk_docs          {"docs":[...]} -> {"results":[...]}
POST   /db/:db/_bulk_get           {"ids":[...]}  -> {"results":[...]}
POST   /db/:db/find                {"where":[...],"limit":10} -> rows
POST   /db/:db/query               BQL (ndjson rows; SUBSCRIBE over SSE)
GET    /db/:db/query?q=            the same, for EventSource clients
GET    /db/:db/changes            changes feed (JSON, or SSE via Accept)

GET    /db/:db/_history            audit trail (see audit-provenance guide)
GET    /db/:db/doc/:id/_versions[/:rev]   past versions and bodies

GET    /db/:db/_timeline           lineage; POST .../branch, .../merge
POST   /db/:db/_sync/*             replication wire (see synchronization)

PUT    /db/:db/doc/:id/att/:name   body = raw bytes
GET    /db/:db/doc/:id/att/:name   fetch attachment bytes
DELETE /db/:db/doc/:id/att/:name   delete attachment

POST   /db/:db/vector              {"id","text","metadata","vector"}
POST   /db/:db/search/vector       {"vector":[...],"k":10}
POST   /db/:db/search/bm25         {"query":"...","k":10}
POST   /db/:db/search/hybrid       {"query":"...","k":10}

POST|GET /spaces, /spaces/:space, .../grants, .../sessions, /handoffs
                                   the agent layer (see the spaces guide)
POST|GET /contexts, /contexts/:id, /contexts/_query, /worksets, ...
                                   contexts and working sets (below)
POST|GET /mcp                      the MCP endpoint (see the mcp guide)

Find documents by field

POST /db/:db/find takes where, a list of conditions in the replication filter form, plus optional limit, offset, include_docs and id_prefix. An invalid query answers 400 invalid_query.

$ curl -XPOST localhost:8080/db/mydb/find -H 'content-type: application/json' \
    -d '{"where": [["path", ["kind"], "user"]], "limit": 10}'
{"rows":[...],"meta":{...}}

Bound a query and read what answered

POST /db/:db/query takes the statement as raw BQL text, or as JSON with query, params, continuation, max_rows and deadline_ms. GET takes the same as ?q=, ?max_rows=, ?deadline_ms=.

$ curl -XPOST localhost:8080/db/mydb/query -H 'content-type: application/json' \
    -d '{"query": "SELECT id, title FROM c ORDER BY id LIMIT 2", "max_rows": 100, "deadline_ms": 2000}'
{"row":{"id":"a","title":"hello"}}
{"row":{"id":"b","title":"world"}}
{"meta":{"has_more":false,"bound":"limit_reached","instance_id":"19ab40285574d671","last_seq":"AAABoNO_U7sAAAAE"}}
  • max_rows caps the rows streamed (at most 1000); deadline_ms bounds the request (at most 300000). A value that is not a positive integer answers 400 invalid_max_rows or invalid_deadline_ms.
  • The last line is {"meta": ...}: bound is limit_reached when the cap cut the stream or the statement's LIMIT or k was filled (more rows may exist), exhausted otherwise; instance_id and last_seq (base64url) name the state of the database that answered; continuation is present when the statement pages.
  • A vector_top_k answer adds embedding: {fingerprint, distance, dimensions} to the meta, so a caller merging answers from several databases can check that their scores compare.
  • When the deadline passes after rows started, the stream ends with an in-band {"error":"deadline"} line and no meta. Any other failure after the first row ends the same way with its reason.

Contexts and working sets

The contexts route group serves context cards, federated queries, and working sets. The contexts guide walks through each call with real responses.

POST   /contexts                    register a card (201)
GET    /contexts                    list (?prefix=, ?unlisted=true); ?q= discovers
GET    /contexts/:id                one card, by id or URL-encoded name
DELETE /contexts/:id                unregister
GET    /contexts/_capabilities      accepted query shapes, merges, limits, budgets
POST   /contexts/_query             one BQL statement over several contexts
GET    /contexts/_offline           {"offline": bool}
PUT    /contexts/_offline           {"offline": true | false}

POST   /worksets                    create ({"owner", "budget"}, 201)
GET    /worksets                    list
GET    /worksets/:ws                read one
DELETE /worksets/:ws                delete it and its slices
POST   /worksets/:ws/members        attach {"context", "mode", "credential_ref"}
DELETE /worksets/:ws/members/:ctx   detach
POST   /worksets/:ws/_materialize   save a query's documents as slices
POST   /worksets/:ws/_import        import an exported snapshot {"dir", "name"}
$ curl -XPOST localhost:8080/contexts/_query -H 'content-type: application/json' \
    -d '{"query": "SELECT id, path FROM c ORDER BY path LIMIT 10",
         "contexts": ["otp/tools", "otp/sasl"]}'

The answer (200) carries execution (succeeded, partial, failed), rows or groups, one sources entry per context, coverage, and a summary. A context that did not answer is reported in its source, not as a request error. A request error answers one shape with an HTTP status per code (400 for a bad argument or statement, 404 unknown_context, 409 ambiguous_context, 413 over_budget, 403 forbidden, 502 source_unavailable, 500 internal):

{"error": "limit_required",
 "message": "A row query over contexts needs a LIMIT.",
 "hint": "Add LIMIT n (n <= 1000), and ORDER BY a selected field to merge rows in order.",
 "details": {"max_limit": 1000}}

A capability token can read cards and run POST /contexts/_query; each local context is checked as a POST /db/:db/query on that database. Registering cards, working sets, imports and switching offline need a global token. Tokens for remote servers live in the node's ctx_credentials, never in a card.

Auth

Unconfigured, the server is open. Set bearer tokens to lock it:

{barrel_server, [{auth, #{tokens => [<<"s3cret">>]}}]}

Every route except /health then requires Authorization: Bearer <token>. Two kinds of bearer: global tokens (the list above, full access, a list makes rotation possible) and capability tokens (bsp_..., issued per space by barrel_caps). A capability token authenticates the /spaces and /handoffs routes, and its own space's /db/:db/* routes when :db is the granted space: read opens the pull leg (GETs, changes, query, search, and the _sync reads), write adds document writes and the push leg (_sync/doc PUT, _sync/local and _sync/att writes). Database lifecycle (PUT/DELETE /db/:db), _timeline, and any unmapped route stay off-limits to capability tokens (403, fail closed); for the contexts routes see Contexts and working sets. A dead or unknown token answers 401; a live token used on another space, or without the right the route needs, answers 403. /mcp authenticates through its own provider covering both kinds. See spaces, mcp, and barrel-lite.

The bearer behavior above is unchanged and is what you get with no extra config. Two stronger methods are opt-in, added by an accept list on the same auth key (its absence leaves everything exactly as described above): Ed25519 signed requests (replay-protected, no TLS required) and an mTLS transport gate. accept => [bearer, signed] accepts either, so a fleet can roll over node by node. See the synchronization guide for the config and the client side.

CORS

Browser clients need CORS. Unconfigured, no CORS headers are sent; set an origin policy to enable it:

{barrel_server, [{cors, #{
    origins => '*',                        %% or [<<"https://app.example">>]
    expose  => [<<"x-barrel-hlc">>,        %% default; the client folds this
                <<"x-barrel-digest">>, <<"x-barrel-att-length">>],
    max_age => 600
}}]}

Preflight OPTIONS requests are answered without a bearer, and error responses still carry CORS headers so browser JS can read them. /mcp keeps its own origin policy. See barrel-lite.

Examples

$ curl -X PUT localhost:8080/db/mydb
{"db":"mydb","ok":true}

$ curl -X PUT localhost:8080/db/mydb/doc/a \
    -H 'content-type: application/json' -d '{"title":"hello"}'
{"id":"a","ok":true,...}

$ curl localhost:8080/db/mydb/doc/a
{"_rev":"000001a1ba3fd05d00000000@w4f0cb98700ad5ffc","id":"a","title":"hello"}

$ curl -X POST localhost:8080/db/mydb/_bulk_docs \
    -H 'content-type: application/json' -d '{"docs":[{"id":"b"},{"id":"c"}]}'
{"results":[{"id":"b",...},{"id":"c",...}]}

$ curl localhost:8080/db/mydb/changes
{"changes":[{"id":"a","rev":"000001a1ba3fd05d00000000@w4f0cb98700ad5ffc","hlc":"..."}],"last":"..."}

Notes

  • The changes feed returns JSON by default. Request Accept: text/event-stream (or ?feed=sse) for Server-Sent Events (one-shot: the current window then close). ?feed=continuous holds the SSE stream open, pushing each change as a data line with a 30s heartbeat, until the client disconnects. ?since=<cursor> takes a cursor from a prior response's last field (or a change's hlc).
  • Databases open with the default vector store (768-dim, BM25 off). The /search/bm25 and /search/hybrid endpoints need BM25 enabled, and hybrid needs an embedder.
  • Optimistic concurrency: PUT /db/:db/doc/:id with a _rev in the body that is not the current winner answers 409 {"error":"conflict"}.
  • Replication over the wire ships today (the /db/:db/_sync/* endpoints; see synchronization), with bearer, Ed25519 signed-request, and mTLS auth (all opt-in; bearer is the default). HTTP/2 and HTTP/3 serving ship (opt-in via listeners); note H3 is TLS-serving but not yet a client-cert gate. gRPC, WebTransport, a unix-socket adapter, and OpenAPI are later phases.

From docs/guides/rest-server.md in the barrel repository at 794415d, updated 2026-11-14 Edit this page View as Markdown

Up and down to moveEnter to open