Skip to content

Docbank for agents

Docbank is a document system of record with an agent-ready interface, not a database that an automation should open directly. One daemon owns the vault. The CLI, agents, scripts, and external applications all use its authenticated HTTP contract and therefore share the same validation, concurrency, integrity, and maintenance rules.

This makes Docbank useful when an agent needs to file, retrieve, reorganize, or verify documents without taking ownership of their physical storage format.

What the contract gives an agent

Stable identity

Node IDs survive renames and moves; immutable SHA-256 identities describe file content.

Conflict evidence

Revisions and If-Match turn stale read-modify-write decisions into explicit HTTP 412 responses.

Byte evidence

Uploads declare hash and size; downloads can be checked against headers, a verified digest trailer, and the node record.

Bounded automation

Pagination, search limits, structured problem codes, dry runs, and NDJSON progress avoid scraping human output.

In prose: node IDs survive renames and moves while immutable SHA-256 identities describe content, so an agent's references stay valid across reorganization. Revisions with If-Match preconditions turn stale read-modify-write races into explicit HTTP 412 conflicts instead of silent overwrites. Uploads declare hash and size, and downloads carry digest evidence, so byte identity is checked rather than assumed. Node listings and search are bounded, and errors and maintenance are structured — pagination and search limits where the contract defines them, problem codes, dry runs, NDJSON progress — so automations never scrape human-oriented output.

Choose the right surface

Surface Use it for Contract
CLI Human-directed work, shell scripts, and inspecting behavior Readable output; machine modes where documented
HTTP API Independent applications and long-running agent workflows Authenticated JSON, revisions, pagination, structured errors
OpenAPI Client generation and capability discovery docbank openapi --json, /openapi.json, /openapi.yaml
Markdown docs Context retrieval without HTML scraping Every public /foo/ page is also published at /foo.md

The detailed Agent Integration Guide covers endpoint setup, authentication, upload and download proof, revision-aware mutations, backup progress, error handling, and a complete safe filing loop. The HTTP API page explains the design contract and non-goals.

The mental model

  1. The daemon is the authority. Never open docbank.db, rewrite pack files, or infer live content from filesystem layout.
  2. IDs identify nodes; paths describe current placement. Retain a node ID after inspecting it. Re-resolve paths when the intent is path-specific.
  3. Content identity is immutable. A file node names a stable current-version UUID plus SHA-256 and size. List or retrieve versions by stable ID; put adds verified bytes and revert adds a new head from a prior version rather than modifying stored history in place.
  4. A stream is not verified until it finishes. Read through successful EOF and require the digest evidence before publishing downloaded bytes.
  5. Destruction has stages. Trash is recoverable; trash empty removes tree history; GC removes unreachable loose bytes or marks packed payload dead; repack reclaims physical packed space.
  6. Dry run before policy-changing maintenance. Preview destructive work, evaluate the result, then make the separate explicit run request.

Common agent workflows

  • File local material: preflight large server-side trees with the intended exclusions, require no errors or over-limit files, then ingest with the same selection and inspect every added, skipped, excluded, and failed result.
  • Write from another machine: upload one file with declared SHA-256, size, name, and destination directory ID; accept success only when the returned server-computed identity matches.
  • Resolve known bytes: query content references by canonical SHA-256 before uploading; inspect every bounded result because the same bytes may be current or historical on several live or trashed nodes.
  • Replace an inspected file: retain its node ID and revision, send raw bytes with declared SHA-256 and size, and require the returned node, new version, computed identity, and ETag to agree before accepting success.
  • Adopt a prior version: retain the target node ID and revision, select a version belonging to it, and require the reversion receipt's node, source, new head, content authority, and ETag to agree. No byte transfer is involved.
  • Reorganize after inspection: read by ID, retain the revision, and mutate with If-Match. On stale_revision, re-read and reconsider rather than blindly replaying the action.
  • Retrieve for another system: stage the response privately, hash while reading, require successful EOF and the digest trailer, then publish.
  • Protect a workflow boundary: create a tagged incremental snapshot, follow structured progress to a terminal result, and verify the repository on the schedule appropriate for its storage medium.

Start integrating

  1. Generate the current contract with docbank openapi --json.
  2. Configure a stable loopback port and strong API key.
  3. Follow the integration guide through health, authentication, bounded reads, and a revision-aware filing loop.
  4. Treat the running OpenAPI document and structured problem codes as the wire authority; treat these pages as the maintained operating model.