API

NullPantry is self-describing: a running instance publishes its full OpenAPI manifest at /v1/openapi.json. Request dispatch, that OpenAPI document, and the SDK manifest at /v1/sdk/manifest are all generated from one route catalog — 197 paths and 279 method-operation pairs, every one served under /v1 — so this page is the map, and the running server is the territory.

curl -sS -H 'Authorization: Bearer dev-token' http://127.0.0.1:8765/v1/openapi.json

Route groups#

Retrieval routes share one pipeline: actor claims → ACL filter → keyword and/or vector candidates (the strategy — keyword-only, vector-only or hybrid — is chosen per query) → reciprocal-rank fusion → optional LLM rerank → citation-safe results. A response is only valid if every cited source, atom, relation and chunk is visible to the requesting actor. Retrieval rollout policies (/v1/lifecycle/rollout) can canary or shadow a new configuration on a percentage of traffic.

Vector maintenance#

/v1/vector/status, /v1/vector/embed, /v1/vector/upsert, /v1/vector/search, /v1/vector/delete, /v1/vector/rebuild, /v1/vector/reconcile, /v1/vector/outbox, /v1/vector/outbox/run.

Diagnostics#

curl -sS -H 'Authorization: Bearer prod-secret' http://127.0.0.1:8765/v1/health
curl -sS -H 'Authorization: Bearer prod-secret' http://127.0.0.1:8765/v1/vector/status

Status routes also exist for optional projections: /v1/lifecycle/analytics/status, /v1/lifecycle/lucid/status.

Auth model#

Authentication is bearer-token. A token maps to a principal: an actor_id, a set of scopes, and a set of capabilities.

Capabilities (7): read, propose, write, verify, delete, export, feed_apply.

Read and write scopes are separate — project:nullpantry does not imply write:project:nullpantry. Single-token setups use NULLPANTRY_TOKEN + NULLPANTRY_SCOPES + NULLPANTRY_CAPABILITIES; multi-actor setups use NULLPANTRY_TOKEN_PRINCIPALS. See NullClaw memory for principal examples.

Without any token configured, the server refuses to bind a non-loopback address; --allow-no-auth-non-loopback is the deliberate override.

Request headers X-NullPantry-Actor-Id, X-NullPantry-Actor-Scopes and X-NullPantry-Actor-Capabilities can narrow a token's permissions, never widen them.

Hard limits#

Fixed server-side defaults: 2 MB max request body, 64 KB max headers, 128 concurrent connections, 30-second socket timeouts. Outbound provider URLs must be HTTPS unless the host is local or insecure HTTP is explicitly allowed, and per-provider circuit breakers guard embedding and LLM calls.

Runtime flags#

Roughly 150 --flags exist; zig build run -- --help is the authoritative list. A flag missing its value is a hard error. The common ones:

Environment variables#

212 distinct NULLPANTRY_* variables are recognised, parsed against a compile-time allowlist. Precedence: config file < environment < CLI flags. NULLPANTRY_HOME and NULLPANTRY_CONFIG select paths before the config file is loaded, so they must come from the real process environment or a CLI flag.

Per-backend variables (NULLPANTRY_QDRANT_URL, NULLPANTRY_MEM0_API_KEY, …) are listed in Backends.

Config file shape#

The file is --config PATH / NULLPANTRY_CONFIG, or nullpantry.json inside --home / NULLPANTRY_HOME. Recognised sections: server, storage, auth, actor, worker, filesystem, provider, retrieval, chunker, agent_memory, vector, graph, analytics, lucid. Sections are strict — unknown keys or wrong types fail at startup:

{
  "server": { "host": "127.0.0.1", "port": 8765 },
  "storage": { "backend": "postgres", "postgres_url": "postgres://user:pass@host:5432/nullpantry" },
  "auth": {
    "token_principals": {
      "agent-a-token": {
        "actor_id": "agent:a",
        "scopes": ["project:nullpantry", "write:project:nullpantry"],
        "capabilities": ["read", "write", "propose", "delete"]
      }
    }
  },
  "agent_memory": { "backend": "redis", "redis": { "url": "redis://redis.internal:6379/0" } },
  "vector": { "backend": "pgvector", "pgvector": { "url": "postgres://host/nullpantry_vectors" } }
}