Skip to main content
POST
/
brain
/
retrieve
curl --request POST \
  --url https://api.atlas.bsyncs.com/brain/retrieve \
  --header 'X-API-Key: atlas_your_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What database does Project Apollo use?",
    "user_id": "user-123",
    "k": 5
  }'

{
  "context": "- Project Apollo uses PostgreSQL (high confidence, via semantic)\n- PostgreSQL is hosted on AWS RDS (high confidence, via semantic)",
  "facts": [
    {
      "fact": "Project Apollo uses PostgreSQL",
      "score": 1.06,
      "source_type": "semantic",
      "V": 0.74,
      "R": 0.999,
      "F": 1.0,
      "A": 0.23
    },
    {
      "fact": "PostgreSQL is hosted on AWS RDS",
      "score": 0.81,
      "source_type": "semantic",
      "V": 0.61,
      "R": 0.998,
      "F": 0.8,
      "A": 0.15
    }
  ],
  "episodic_count": 0,
  "semantic_count": 2,
  "latency_ms": 340
}

​
Authorizations

​
X-API-Key
string
required
Your Atlas API key. Format: atlas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

​
Body

​
query
string
required
Natural language query. Write it as a question or topic — Atlas extracts keywords and resolves them to canonical entity names automatically.
​
user_id
string
required
Namespace identifier. Overridden server-side from your API key.
​
k
integer
default:"5"
Number of facts to return. Increase for broader context, decrease for precision.
​
session_id
string
Restrict retrieval to a session sub-namespace. Only returns facts ingested with the same session_id.
​
include_episodic
boolean
default:"true"
Include results from Qdrant vector store (episodic memory).
​
include_semantic
boolean
default:"true"
Include results from Neo4j knowledge graph (semantic memory). Set to false for faster vector-only retrieval.
​
max_hops
integer
default:"2"
Graph traversal depth for semantic retrieval.
1 = direct facts only. 3 = deep relational traversal.
Increasing beyond 3 significantly raises latency.
​
scoring_weights
object
Override the hybrid scoring weights α·V + β·R + γ·F + δ·A.
  {
    "alpha": 0.20,
    "beta": 0.70,
    "gamma": 0.10,
    "delta": 0.50
  }
KeySignalDefault
alphaSemantic similarity0.20
betaRecency0.70
gammaAccess frequency0.10
deltaRelation alignment0.50

​
Response

​
context
string
Pre-formatted string ready for LLM system prompt injection.
Pass directly to messages[0].content — no parsing needed.
​
facts
array
Ranked list of individual facts with score breakdown.
​
episodic_count
integer
Number of facts returned from Qdrant (vector).
​
semantic_count
integer
Number of facts returned from Neo4j (graph).
​
latency_ms
float
Total retrieval time in milliseconds.
curl --request POST \
  --url https://api.atlas.bsyncs.com/brain/retrieve \
  --header 'X-API-Key: atlas_your_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What database does Project Apollo use?",
    "user_id": "user-123",
    "k": 5
  }'

{
  "context": "- Project Apollo uses PostgreSQL (high confidence, via semantic)\n- PostgreSQL is hosted on AWS RDS (high confidence, via semantic)",
  "facts": [
    {
      "fact": "Project Apollo uses PostgreSQL",
      "score": 1.06,
      "source_type": "semantic",
      "V": 0.74,
      "R": 0.999,
      "F": 1.0,
      "A": 0.23
    },
    {
      "fact": "PostgreSQL is hosted on AWS RDS",
      "score": 0.81,
      "source_type": "semantic",
      "V": 0.61,
      "R": 0.998,
      "F": 0.8,
      "A": 0.15
    }
  ],
  "episodic_count": 0,
  "semantic_count": 2,
  "latency_ms": 340
}