Agent Context API

The Agent Context API is served by the Bundata API server under /api/agent/v1. Every request authenticates with a scoped credential created in Settings → Agent access (Authorization: Bearer bdk_<16 hex>_<43 base64url>).

Credentials and scopes

Workspace owners and admins (agent_credential:manage) manage up to 50 active credentials per stored workspace (POST /api/w/:wsId/agent-credentials). Each credential expires after 1 to 365 days, acts with its creator’s live workspace membership (AGENT_CREDENTIAL_AUTHORITY_LOST if permissions are revoked), and refuses browser requests (Origin or Sec-Fetch-* headers return 403 AGENT_BROWSER_REQUEST_REFUSED).

Context packs and replays

POST /api/agent/v1/context-packs (and /api/agent/v1/context-packs/stream for application/x-ndjson) builds a deterministic, ranked, deduplicated evidence pack within a token budget:

curl -sS "$BUNDATA_URL/api/agent/v1/context-packs" \
  -H "Authorization: Bearer $BUNDATA_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Who is the current CFO, and since when?",
    "budget": { "maxTokens": 2000, "coverage": "best_effort" },
    "asOf": { "validTime": "2025-01-01T00:00:00Z" }
  }'

• Request fields: task (1–4,000 chars), budget.maxTokens (256–32,000, default 4,000), budget.maxLatencyMs (1,000–60,000, default 15,000), budget.coverage (best_effort or require_complete), asOf (validTime, systemTime), filters (collectionIds up to 8, documentIds up to 20, sources: passages, graph, documents), retrieval (hybrid or lexical), and optional contextSetId.
• Set-first packing: When contextSetId is passed (or the credential is bound to one active Context set), the pack fills its budget in order: verified_answers, definitions, instructions (marked trust: "approved"), required_evidence, evidence, and whole_document.
• Untrusted document text: Every item quoted from a document is marked trust: "untrusted", includes validity, superseded, and contradiction flags, and is re-checked for read access before release.
• Replay (POST /api/agent/v1/replays/:replayId with { "mode": "verify" | "recompute", "task"?: string }): Re-verifies every recorded item against current documents (unchanged, changed, unavailable) or recomputes the pack at the recorded times and returns a diff. Replay records store hashes only and expire after 30 days (410 AGENT_REPLAY_EXPIRED).

Context set and library routes

All four routes require context:read, match words deterministically without spending provider embedding budget, and enforce context-set scope:

• POST /api/agent/v1/context-sets/list ({ query?, limit? })
• POST /api/agent/v1/context-sets/get ({ contextSetId? })
• POST /api/agent/v1/definitions/lookup ({ term, contextSetId?, limit? })
• POST /api/agent/v1/verified-answers/match ({ question, contextSetId?, limit? })

Studied fields and query templates

• Studied fields (POST /api/agent/v1/fields/list and POST /api/agent/v1/fields/query, scope context:read): Inspect a collection’s normalized studied fields (number, money, date, boolean, text) and execute structured plans (up to 6 fields, 6 filters, sort, limit up to 200, and aggregate count/min/max/sum/avg with groupBy up to 50 groups, plus optional knownAt: "YYYY-MM-DD"). Every returned value includes a live-checked passage span citation (citation or null with uncitedReason), and coverageLines / incomplete report whether any field is stated in fewer than 90% of documents.
• Query templates (POST /api/agent/v1/query-templates/run, scope queries:run): Execute an approved PostgreSQL query template belonging to the active context set by passing { templateId, parameters, contextSetId? }. Agents never send or receive raw SQL.