APIUpdated 2026-05-30

Company Brain API

Ask the company brain from agents, backends, workers, and automation.

Applies to: RetainDB API v1

Use POST /v1/context when an agent needs grounded company knowledge.

This route searches indexed sources, source-derived memories, and project knowledge, then returns an agent-ready context payload. Use it for company facts. Use /v1/memory/search for user or session memory.

Endpoint

http

POST https://api.retaindb.com/v1/context
Authorization: Bearer $RETAINDB_API_KEY
Content-Type: application/json

Example

bash

curl -X POST "https://api.retaindb.com/v1/context" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "production",
    "query": "What does our checkout documentation say about failed payments?",
    "max_results": 10
  }'

Request Body

Field	Type	Required	Notes
`project`	string	yes	Project, workspace, or environment to query
`query`	string	yes	Natural-language question or retrieval query
`max_results`	number	no	Preferred modern limit field
`top_k`	number	no	Compatibility limit field
`source_ids`	string[]	no	Restrict retrieval to specific sources
`include_memories`	boolean	no	Include matching source-derived/project memories where supported
`include_debug`	boolean	no	Include timing/debug metadata where enabled

Use source_ids when an agent is answering from a specific source picker or when you want to compare two sources directly.

Response Shape

Typical response:

json

{
  "context": "Relevant company context...",
  "answer": null,
  "matches": [
    {
      "id": "chunk_...",
      "score": 0.84,
      "text": "Billing retries happen for 3 days...",
      "source": {
        "id": "src_...",
        "name": "Billing Runbook",
        "type": "text"
      },
      "document": {
        "id": "doc_...",
        "title": "Billing Runbook"
      }
    }
  ],
  "memories": [],
  "citations": [],
  "meta": {
    "latency_ms": 102,
    "trace_id": "trc_..."
  }
}

Fields may vary by deployment and enabled retrieval features, but callers should expect:

context: formatted text safe to place before a model call
matches: source/document/chunk-level retrieval results
memories: relevant memory records when available
citations: citation objects or source references when available
meta: timing, trace, and debug metadata

Empty Results

An empty result usually means one of these:

Cause	Check
Wrong project	Confirm dashboard project matches API `project`
Source not indexed	Call `GET /v1/sources?project=...`
Query too vague	Ask about words that appear in the source
Source deleted or paused	Check source status
Access policy filtered it	Check key scope and source permissions

Prompt Pattern

Pass RetainDB context into your model as evidence:

txt

Use the following RetainDB company context when relevant.
If the context is insufficient, say what is missing instead of guessing.

{context}

Surface	Equivalent
Dashboard	Company Brain page
MCP	`context` tool
SDK	`client.context.query(...)` or `client.query(...)`
Agent filesystem	`GET /v1/context/files`

Compatibility

POST /v1/context/query remains available as a compatibility alias. New docs, SDK examples, MCP flows, and agent integrations should use POST /v1/context.

Next: Sources API, Connect Agents, or Memory API.

Was this page useful?

Your feedback helps us make the product easier to ship with.