Query the ExoBrain

curl --request POST \
  --url https://api.get-exo.com/v1/brain/query \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "question": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/brain/query"

payload = { "question": "<string>" }
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({question: '<string>'})
};

fetch('https://api.get-exo.com/v1/brain/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "alias": "<string>",
  "confidence": 123,
  "focal": [
    {
      "cosine_in_seed": true,
      "node_id": "<string>",
      "snippet": "<string>"
    }
  ],
  "latency_ms": 123,
  "question": "<string>",
  "subgraph": {},
  "tenant_id": "<string>",
  "tier": "<string>",
  "contradictions": [
    {}
  ],
  "cosine_top": [
    {}
  ],
  "drift_rate": 0,
  "model_params": 0,
  "negative_edges_in_subgraph": 0,
  "system_used": "?",
  "use_system2": false
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

POST

brain

query

Query the ExoBrain

curl --request POST \
  --url https://api.get-exo.com/v1/brain/query \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "question": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/brain/query"

payload = { "question": "<string>" }
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({question: '<string>'})
};

fetch('https://api.get-exo.com/v1/brain/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "alias": "<string>",
  "confidence": 123,
  "focal": [
    {
      "cosine_in_seed": true,
      "node_id": "<string>",
      "snippet": "<string>"
    }
  ],
  "latency_ms": 123,
  "question": "<string>",
  "subgraph": {},
  "tenant_id": "<string>",
  "tier": "<string>",
  "contradictions": [
    {}
  ],
  "cosine_top": [
    {}
  ],
  "drift_rate": 0,
  "model_params": 0,
  "negative_edges_in_subgraph": 0,
  "system_used": "?",
  "use_system2": false
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

Run one ExoBrain forward pass over the org’s knowledge graph and return the glass-box result: the focal nodes the model settled on, the cosine top-K head for comparison, gate confidence, drift rate, propagation tier and any contradictions among the activated nodes. Requires a trained brain for the org (see POST /v1/brain/train); returns 404 when no brain artifact exists yet, and 409 while a newly published artifact is still being picked up. This route reads the API key owner’s own content, so the X-Exo-Subject selector is not accepted here.

Authorization

This route requires the read scope. A missing or invalid credential returns 401 authentication_error. A valid credential without the scope returns 403 permission_denied, and the problem body names the exact scope required.

Headers

These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below.

Header	Applies	What it does
`X-Exo-API-Key`	Required	Your Exo API key, `exo_<env>_<token>`. `Authorization: Bearer exo_...` is accepted as an alternate.
`X-Exo-Subject`	Refused	This route scopes data by the key owner. Sending the header returns 400 `subject_not_supported`, rather than silently reading the wrong partition.
`Idempotency-Key`	Not honoured	This route does not replay: reads have no side effect to replay.
`X-Request-Id`	Response	Returned on every response, including `204`s. Quote it in a support request.

Success responses

Status	Meaning
`200`	The focal set, cosine head and cognitive signals from the forward pass.

Errors

Status	Code	When
`400`	`invalid_request`	Malformed request, for example an invalid cursor.
`401`	`authentication_error`	Missing or invalid credentials.
`403`	`permission_denied`	Missing scope, or an unprovisioned subject selector.
`404`	`not_found`	The resource does not exist, or is not visible to this caller.
`409`	`conflict`	A conflict with the current state of the resource.
`422`	`validation_error`	The request was understood but failed field validation.
`429`	`rate_limit_exceeded`	Rate limit exceeded. Retry after the Retry-After interval.
`503`	`service_degraded`	A dependency is temporarily unavailable. Safe to retry.

Every error is an RFC 9457 application/problem+json body carrying a stable code, a requestId, and a suggestedAction where Exo has one. See Errors.

Notes

Requires a trained brain. No artifact yet is 404, and a freshly published artifact that is still being picked up is 409.
This route reads the key owner’s own content. X-Exo-Subject is refused with 400 subject_not_supported rather than silently ignored.

Authorizations

X-Exo-API-Key

string

header

required

An Exo API key (exo_...) sent as the X-Exo-API-Key header.

Body

application/json

An ExoBrain forward-pass request.

question

string

required

Free-text query.

focal_display

integer

default:5

How many focal nodes to return.

Required range: 1 <= x <= 20

seed_k

integer

default:200

Cosine top-K seed set size (controls tier).

Required range: 10 <= x <= 2000

Response

The focal set, cosine head and cognitive signals from the forward pass.

The glass-box result of one ExoBrain forward pass.

focal is the working-memory set the model settled on, cosine_top is the plain nearest-neighbour head for comparison, and confidence / drift_rate / tier / use_system2 are the cognitive signals that drove the propagation.

alias

string

required

confidence

number

required

focal

BrainFocalNode · object[]

required

Show child attributes

latency_ms

number

required

question

string

required

subgraph

Subgraph · object

required

Show child attributes

tenant_id

string

required

tier

string

required

contradictions

Contradictions · object[]

cosine_top

Cosine Top · object[]

Cosine top-K head for comparison (node_id, score, snippet).

drift_rate

number

default:0

model_params

integer

default:0

negative_edges_in_subgraph

integer

default:0

system_used

string

default:?

use_system2

boolean

default:false

Get ExoBrain status

Answer with brain conditioning

⌘I

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Body

Response

Authorization

Headers

Success responses

Errors

Notes