BrainAPI Retrieve API

For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.

Retrieve

Retrieve data from the knowledge graph and data store.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

text*Text

The text to search for.

limit?Limit

The number of results to return.

Default10

preferred_entities*Preferred Entities

The entities to prioritize in the relationships, separated by commas.

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

`application/json`

curl -X GET "https://example.com/retrieve/?text=string&preferred_entities=string"

{  "data": [    {      "brain_version": "0.0.0",      "id": "string",      "inserted_at": "2019-08-24T14:15:22Z",      "metadata": {},      "text": "string"    }  ],  "observations": [    {      "id": "string",      "inserted_at": "2019-08-24T14:15:22Z",      "metadata": {},      "resource_id": "string",      "text": "string"    }  ],  "relationships": [    {}  ]}

Get Changelogs List

Retrieve a paginated list of changelogs.

Parameters: types (Optional[str]): Optional comma-separated changelog types to filter by; each type will be applied as a filter. query_text (Optional[str]): Optional text used to filter changelogs by content or metadata.

Returns: list: Changelog records matching the provided filters, constrained by limit and skip.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

types?string|null

query_text?string|null

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/changelogs"

{  "changelogs": [    {      "change": {        "object": {          "description": "string",          "labels": [            "string"          ],          "name": "string",          "properties": {},          "uuid": "string"        },        "predicate": {          "amount": 0,          "description": "string",          "name": "string",          "properties": {},          "uuid": "string"        },        "subject": {          "description": "string",          "labels": [            "string"          ],          "name": "string",          "properties": {},          "uuid": "string"        },        "type": "relationship_created"      },      "id": "string",      "timestamp": "2019-08-24T14:15:22Z",      "type": "relationship_created"    }  ],  "count": 0,  "message": "string"}

Get Changelog Types

Retrieve all unique changelog types for the specified brain.

Parameters: brain_id (str): Identifier of the brain to query; defaults to "default".

Returns: list[str]: List of unique changelog type names.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/changelogs/types"

{  "count": 0,  "message": "string",  "types": [    "string"  ]}

Get Changelog By Id

Retrieve a changelog entry by its unique identifier.

Parameters: id (str): Unique identifier of the changelog entry. brain_id (str): Brain identifier to query. Defaults to "default".

Returns: The changelog entry corresponding to the specified identifier.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Path Parameters

id*Id

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/changelogs/string"

{  "changelog": {    "change": {      "object": {        "description": "string",        "labels": [          "string"        ],        "name": "string",        "properties": {},        "uuid": "string"      },      "predicate": {        "amount": 0,        "description": "string",        "name": "string",        "properties": {},        "uuid": "string"      },      "subject": {        "description": "string",        "labels": [          "string"        ],        "name": "string",        "properties": {},        "uuid": "string"      },      "type": "relationship_created"    },    "id": "string",    "timestamp": "2019-08-24T14:15:22Z",    "type": "relationship_created"  },  "message": "string"}

Get Context

Handle an HTTP request to retrieve an entity's contextual information.

Parameters: request (GetContextRequestBody): Request body containing: - text: The text to search context for. - brain_id: The brain/workspace identifier to query.

Returns: GetContextResponse: Response containing the context information.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for the get context endpoint.

apply_fact_filter?Apply Fact Filter

Defaulttrue

brain_id?Brain Id

Default"default"

cross_event_bridges?Cross Event Bridges

Range0 <= value

Default3

historical_limit?Historical Limit

Default10

max_facts?Max Facts

Range0 <= value

Default40

max_passages?Max Passages

Default8

profile_stages?Profile Stages

Defaultfalse

sufficiency_retry?Sufficiency Retry

Defaultfalse

text*Text

use_ppr?Use Ppr

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/retrieve/context" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'

{  "graph_session_ids": [    "string"  ],  "historical_context": [],  "paths": [    {}  ],  "source_passages": [],  "stage_timings": {},  "temporal_conflicts": [    {}  ],  "text_context": "string",  "topics": [    {}  ],  "triples": [    {      "identified_entity": "string",      "source_chunk_ids": [        "string"      ],      "source_session_ids": [        "string"      ],      "triple": [        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        },        {          "amount": 0,          "deprecated": false,          "description": "string",          "direction": "neutral",          "flow_key": "string",          "last_updated": "2019-08-24T14:15:22Z",          "level": "1",          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "properties": {},          "uuid": "string"        },        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        },        {          "amount": 0,          "deprecated": false,          "description": "string",          "direction": "neutral",          "flow_key": "string",          "last_updated": "2019-08-24T14:15:22Z",          "level": "1",          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "properties": {},          "uuid": "string"        },        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        }      ]    }  ]}

Get Entities

Retrieve entities matching optional label and text filters with pagination.

Parameters: node_labels (Optional[str]): Comma-separated node labels to filter by (e.g. "Person,Company"); when provided, only entities with any of these labels are returned. query_text (Optional[str]): Free-text filter to match entity properties or content. brain_id (str): Identifier of the brain/knowledge store to query.

Returns: list: A list of entity records that match the provided filters and pagination parameters.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

node_labels?string|null

query_text?string|null

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/entities"

{  "entities": [    {      "description": "string",      "happened_at": "string",      "labels": [        "string"      ],      "last_updated": "2019-08-24T14:15:22Z",      "metadata": {},      "name": "string",      "observations": [        {          "id": "string",          "inserted_at": "2019-08-24T14:15:22Z",          "metadata": {},          "resource_id": "string",          "text": "string"        }      ],      "polarity": "neutral",      "properties": {},      "uuid": "string"    }  ],  "message": "string",  "total": 0}

Get Neighbors

Get the neighbors of an entity.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

uuid*Uuid

The UUID of the entity to get neighbors for.

limit?Limit

The number of neighbors to return.

Default10

look_for?|

The description of what in the neighbors should share with the target.

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/entities/neighbors?uuid=string"

{  "count": 0,  "main_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  },  "neighbors": [    {      "most_common": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "neighbor": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "relationship": {        "amount": 0,        "deprecated": false,        "description": "string",        "direction": "neutral",        "flow_key": "string",        "last_updated": "2019-08-24T14:15:22Z",        "level": "1",        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "properties": {},        "uuid": "string"      },      "similarity_score": 0    }  ]}

Get Neighbors With Identification Params

Get the neighbors of an entity.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for the retrieve neighbors with identification params endpoint.

brain_id?Brain Id

The brain identifier to store the data in.

Default"default"

identification_params*

The identification parameters of the entity to get neighbors for.

limit?Limit

The number of neighbors to return.

Default10

look_for?|

Optional filter for what type of neighbors to look for.

Response Body

`application/json`

curl -X POST "https://example.com/retrieve/entities/neighbors" \  -H "Content-Type: application/json" \  -d '{    "identification_params": {      "name": "string"    }  }'

{  "count": 0,  "main_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  },  "neighbors": [    {      "most_common": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "neighbor": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "relationship": {        "amount": 0,        "deprecated": false,        "description": "string",        "direction": "neutral",        "flow_key": "string",        "last_updated": "2019-08-24T14:15:22Z",        "level": "1",        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "properties": {},        "uuid": "string"      },      "similarity_score": 0    }  ]}

Get Neighbors Ai Mode

Retrieve neighboring entities using AI-mode identification parameters.

Parameters: request (RetrieveNeighborsAiModeRequestBody): Request body containing: - identification_params: parameters that identify the target entity or entities. - looking_for: description of the desired neighbors or relation types. - limit: maximum number of neighbor results to return.

Returns: list: Neighboring entities that match the AI-mode identification and search criteria.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The request body for the retrieve neighbors AI mode endpoint.

brain_id?Brain Id

The brain identifier to store the data in.

Default"default"

identification_params*

The identification parameters of the entity to get neighbors for.

limit?Limit

The number of neighbors to return.

Default10

looking_for*array<string>|

The description of the neighbors to look for.

Response Body

`application/json`

curl -X POST "https://example.com/retrieve/entities/neighbors/ai-mode" \  -H "Content-Type: application/json" \  -d '{    "identification_params": {      "name": "string"    },    "looking_for": [      "string"    ]  }'

{  "count": 0,  "main_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  },  "neighbors": [    {      "most_common": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "neighbor": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "relationship": {        "amount": 0,        "deprecated": false,        "description": "string",        "direction": "neutral",        "flow_key": "string",        "last_updated": "2019-08-24T14:15:22Z",        "level": "1",        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "properties": {},        "uuid": "string"      },      "similarity_score": 0    }  ]}

Get Entity Context

Retrieve contextual information for an entity identified by target.

Parameters: target (str): Identifier or name of the target entity. context_depth (int): Maximum depth of related context to include. brain_id (str): Identifier of the brain/knowledge graph to query.

Returns: dict: A mapping containing the entity's contextual information.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

target*Target

context_depth?Context Depth

Default3

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/entity/context?target=string"

{  "natural_language_web": [],  "neighborhood": [    {}  ],  "target_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  },  "text_contexts": []}

Get Entity Info

Retrieve detailed information for an entity identified by the given target and query.

Parameters: target (str): Identifier or name of the target entity to retrieve. query (str): Query text used to refine or disambiguate the requested entity information. max_depth (int): Maximum graph depth to traverse when collecting related information. brain_id (str): Identifier of the brain/namespace to query.

Returns: dict: A mapping containing the entity's attributes and related contextual information.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

target*Target

query*Query

max_depth?Max Depth

Default3

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/entity/info?target=string&query=string"

{  "path": {    "children": [      {}    ],    "path": [      {        "amount": 0,        "deprecated": false,        "description": "string",        "direction": "neutral",        "flow_key": "string",        "last_updated": "2019-08-24T14:15:22Z",        "level": "1",        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "properties": {},        "uuid": "string"      },      {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      }    ],    "similarity": 0,    "target_node": {      "description": "string",      "happened_at": "string",      "labels": [        "string"      ],      "last_updated": "2019-08-24T14:15:22Z",      "metadata": {},      "name": "string",      "observations": [        {          "id": "string",          "inserted_at": "2019-08-24T14:15:22Z",          "metadata": {},          "resource_id": "string",          "text": "string"        }      ],      "polarity": "neutral",      "properties": {},      "uuid": "string"    }  },  "target_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  }}

Get Entity Status

Retrieve status information for a specified entity.

Parameters: target (str): Identifier or name of the entity to inspect. types (Optional[List[str]]): Optional list of entity types to filter the status computation. brain_id (str): Identifier of the brain (knowledge graph) to query.

Returns: status (dict): A dictionary containing the entity's status details.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

target*Target

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[index: integer]?string

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/entity/status?target=string" \  -H "Content-Type: application/json" \  -d '[    "string"  ]'

{  "exists": true,  "has_relationships": true,  "node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  },  "observations": [    {      "id": "string",      "inserted_at": "2019-08-24T14:15:22Z",      "metadata": {},      "resource_id": "string",      "text": "string"    }  ],  "relationships": [    [      {        "amount": 0,        "deprecated": false,        "description": "string",        "direction": "neutral",        "flow_key": "string",        "last_updated": "2019-08-24T14:15:22Z",        "level": "1",        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "properties": {},        "uuid": "string"      },      {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      }    ]  ]}

Get Entity Synergies

Retrieve synergies for a specified entity.

Parameters: target: Identifier or name of the target entity. polarity: "same" for matching node polarity; "opposite" for positive↔negative. do: If True, only direct synergies are returned. pa: If True, potential anchors are returned. ppa: If True, seed anchors are returned. top_k: Maximum synergies to return (default 50). labels: Optional candidate label filter. brain_id: Identifier of the knowledge brain to query.

Returns: Synergy records for the target entity matching the requested polarity.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

target*Target

polarity?Polarity

Default"same"

Value in

"same"
"opposite"

do?Do

Defaultfalse

pa?Pa

Defaultfalse

ppa?Ppa

Defaultfalse

top_k?Top K

Default50

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[index: integer]?string

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/entity/synergies?target=string" \  -H "Content-Type: application/json" \  -d '[    "string"  ]'

{  "anchors": [    {      "description": "string",      "happened_at": "string",      "labels": [        "string"      ],      "last_updated": "2019-08-24T14:15:22Z",      "metadata": {},      "name": "string",      "observations": [        {          "id": "string",          "inserted_at": "2019-08-24T14:15:22Z",          "metadata": {},          "resource_id": "string",          "text": "string"        }      ],      "polarity": "neutral",      "properties": {},      "uuid": "string"    }  ],  "potential_anchors": [    {      "description": "string",      "happened_at": "string",      "labels": [        "string"      ],      "last_updated": "2019-08-24T14:15:22Z",      "metadata": {},      "name": "string",      "observations": [        {          "id": "string",          "inserted_at": "2019-08-24T14:15:22Z",          "metadata": {},          "resource_id": "string",          "text": "string"        }      ],      "polarity": "neutral",      "properties": {},      "uuid": "string"    }  ],  "synergies": [    {      "association_score": 0,      "connected_by": [        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        }      ],      "node": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      }    }  ],  "target_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  }}

Get Hops

Compute graph hops for the given query.

Parameters: query (str): Search text or entity identifier to start hop traversal from. degrees (int): Maximum number of hop degrees to traverse (default 2). flattened (bool): If True, return a flattened list of hops; otherwise preserve nested hop structure. brain_id (str): Identifier of the brain (knowledge graph) to query.

Returns: list: Hops (paths) connecting matching entities up to the specified degree; the exact structure varies based on flattened.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

query*Query

degrees?Degrees

Default2

flattened?Flattened

Defaulttrue

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/hops?query=string"

[  [    {      "description": "string",      "happened_at": "string",      "labels": [        "string"      ],      "last_updated": "2019-08-24T14:15:22Z",      "metadata": {},      "name": "string",      "observations": [        {          "id": "string",          "inserted_at": "2019-08-24T14:15:22Z",          "metadata": {},          "resource_id": "string",          "text": "string"        }      ],      "polarity": "neutral",      "properties": {},      "uuid": "string"    },    [      [        {          "amount": 0,          "deprecated": false,          "description": "string",          "direction": "neutral",          "flow_key": "string",          "last_updated": "2019-08-24T14:15:22Z",          "level": "1",          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "properties": {},          "uuid": "string"        },        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        },        [          [            {              "amount": 0,              "deprecated": false,              "description": "string",              "direction": "neutral",              "flow_key": "string",              "last_updated": "2019-08-24T14:15:22Z",              "level": "1",              "name": "string",              "observations": [                {                  "id": "string",                  "inserted_at": "2019-08-24T14:15:22Z",                  "metadata": {},                  "resource_id": "string",                  "text": "string"                }              ],              "properties": {},              "uuid": "string"            },            {              "description": "string",              "happened_at": "string",              "labels": [                "string"              ],              "last_updated": "2019-08-24T14:15:22Z",              "metadata": {},              "name": "string",              "observations": [                {                  "id": "string",                  "inserted_at": "2019-08-24T14:15:22Z",                  "metadata": {},                  "resource_id": "string",                  "text": "string"                }              ],              "polarity": "neutral",              "properties": {},              "uuid": "string"            }          ]        ]      ]    ]  ]]

Get Observations List

Retrieve a list of observations filtered by the provided parameters.

Parameters: limit (int): Maximum number of observations to return. skip (int): Number of observations to skip (offset). resource_id (Optional[str]): If provided, only return observations for this resource identifier. labels (Optional[str]): Comma-separated observation labels to filter by; when provided, labels are treated as a list of strings. query_text (Optional[str]): Full-text query to filter observations. brain_id (str): Identifier of the brain/tenant to query.

Returns: list: A list of observation records that match the provided filters.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

resource_id?string|null

labels?string|null

query_text?string|null

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/observations"

{  "count": 0,  "message": "string",  "observations": [    {      "id": "string",      "inserted_at": "2019-08-24T14:15:22Z",      "metadata": {},      "resource_id": "string",      "text": "string"    }  ]}

Get Observation Labels

Get all unique labels from observations.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/observations/labels"

{  "count": 0,  "labels": [    "string"  ],  "message": "string"}

Get Observation By Id

Get observation by ID.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Path Parameters

id*Id

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/observations/string"

{  "message": "string",  "observation": {    "id": "string",    "inserted_at": "2019-08-24T14:15:22Z",    "metadata": {},    "resource_id": "string",    "text": "string"  }}

Ranked event-graph recommendations composing synergies, asymmetric complementary walks, multi-interest medoids, and optional attribute preferences (retrieval-time only; no training).

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

target*Target

polarity?Polarity

Default"same"

Value in

"same"
"opposite"

top_k?Top K

Default20

include_asymmetric?Include Asymmetric

Defaulttrue

include_multi_interest?Include Multi Interest

Defaulttrue

include_attribute_pref?Include Attribute Pref

Defaultfalse

diversify?Diversify

Defaulttrue

asymmetric_direction?Asymmetric Direction

Default"outbound"

Value in

"outbound"
"inbound"
"both"

exclude_seen?Exclude Seen

Defaultfalse

recency_half_life_days?number|null

dampen_degree?Dampen Degree

Defaultfalse

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[index: integer]?string

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/recommend?target=string" \  -H "Content-Type: application/json" \  -d '[    "string"  ]'

{  "recommendations": [    {      "channel": "string",      "connected_by": [        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        }      ],      "node": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "score": 0    }  ],  "target_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  }}

Post Recommend. See the BrainAPI developer documentation for request, response, authentication, and retry semantics.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for event-graph recommendations.

asymmetric_direction?Asymmetric Direction

Default"outbound"

Value in

"outbound"
"inbound"
"both"

behavior_weights?|null

brain_id?Brain Id

Default"default"

dampen_degree?Dampen Degree

Defaultfalse

diversify?Diversify

Defaulttrue

exclude_seen?Exclude Seen

Defaultfalse

include_asymmetric?Include Asymmetric

Defaulttrue

include_attribute_pref?Include Attribute Pref

Defaultfalse

include_multi_interest?Include Multi Interest

Defaulttrue

labels?array<string>|null

polarity?Polarity

Default"same"

Value in

"same"
"opposite"

recency_half_life_days?|null

target*Target

top_k?Top K

Range1 <= value <= 200

Default20

Response Body

`application/json`

curl -X POST "https://example.com/retrieve/recommend" \  -H "Content-Type: application/json" \  -d '{    "target": "string"  }'

{  "recommendations": [    {      "channel": "string",      "connected_by": [        {          "description": "string",          "happened_at": "string",          "labels": [            "string"          ],          "last_updated": "2019-08-24T14:15:22Z",          "metadata": {},          "name": "string",          "observations": [            {              "id": "string",              "inserted_at": "2019-08-24T14:15:22Z",              "metadata": {},              "resource_id": "string",              "text": "string"            }          ],          "polarity": "neutral",          "properties": {},          "uuid": "string"        }      ],      "node": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "score": 0    }  ],  "target_node": {    "description": "string",    "happened_at": "string",    "labels": [      "string"    ],    "last_updated": "2019-08-24T14:15:22Z",    "metadata": {},    "name": "string",    "observations": [      {        "id": "string",        "inserted_at": "2019-08-24T14:15:22Z",        "metadata": {},        "resource_id": "string",        "text": "string"      }    ],    "polarity": "neutral",    "properties": {},    "uuid": "string"  }}

Get Relationships

Retrieve relationships filtered by types, node labels, and query criteria.

Parameters: relationship_types (Optional[str]): Comma-separated relationship types to include. from_node_labels (Optional[str]): Comma-separated source node labels to filter. to_node_labels (Optional[str]): Comma-separated target node labels to filter. query_text (Optional[str]): Text to match against relationships or nodes. query_search_target (Optional[str]): Target of the text query, such as "all", "source", or "target". limit (int): Maximum number of relationships to return. skip (int): Number of relationships to skip. brain_id (str): Brain (dataset) identifier.

Returns: List of relationship records matching the filters.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

relationship_types?string|null

from_node_labels?string|null

to_node_labels?string|null

query_text?string|null

query_search_target?|

Default"all"

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/relationships"

{  "message": "string",  "relationships": [    {      "object": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      },      "predicate": {        "amount": 0,        "deprecated": false,        "description": "string",        "direction": "neutral",        "flow_key": "string",        "last_updated": "2019-08-24T14:15:22Z",        "level": "1",        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "properties": {},        "uuid": "string"      },      "subject": {        "description": "string",        "happened_at": "string",        "labels": [          "string"        ],        "last_updated": "2019-08-24T14:15:22Z",        "metadata": {},        "name": "string",        "observations": [          {            "id": "string",            "inserted_at": "2019-08-24T14:15:22Z",            "metadata": {},            "resource_id": "string",            "text": "string"          }        ],        "polarity": "neutral",        "properties": {},        "uuid": "string"      }    }  ],  "total": 0}

Get Search

Get Search. See the BrainAPI developer documentation for request, response, authentication, and retry semantics.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

query*Query

The search query.

k?K

Number of hits to return.

Range1 <= value <= 200

Default10

channels?|

Comma-separated channels: passages, entities, events, communities, and/or plugin:.

Default"passages"

node_labels?|

Comma-separated node labels to filter the entities channel.

community_labels?|

Comma-separated hub labels for the communities channel.

expand?Expand

Optional 1-hop expansion from graph channel seeds.

Default"none"

Value in

"none"
"neighbors"

fusion?|

Fusion override. Default is SEARCH_FUSION.

rerank?|

none or plugin:. Unknown plugin names return 400.

target?|

Optional USER uuid or id for query-gated rerank of retrieved hits.

profile_stages?Profile Stages

Defaultfalse

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/search?query=string"

{  "channel_lists": {    "property1": [      "string"    ],    "property2": [      "string"    ]  },  "facets": {    "property1": {      "property1": 0,      "property2": 0    },    "property2": {      "property1": 0,      "property2": 0    }  },  "hits": [    {      "channel": "string",      "extras": {},      "id": "string",      "labels": [        "string"      ],      "node_id": "string",      "score": 0,      "scores": {        "bm25": 0,        "cc": 0,        "dense": 0,        "graph": 0,        "personalize": 0,        "plugin": {          "property1": 0,          "property2": 0        },        "rerank": 0,        "rrf": 0      },      "snippet": "string"    }  ],  "node_ids": [    "string"  ],  "stage_timings": {}}

Post Search

Post Search. See the BrainAPI developer documentation for request, response, authentication, and retry semantics.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

brain_id?Brain Id

Default"default"

channels?array<string>

community_labels?array<string>|null

expand?Expand

Default"none"

Value in

"none"
"neighbors"

extras?|null

fusion?|null

fusion_alpha?|null

k?K

Range1 <= value <= 200

Default10

mode?Mode

Default"default"

Value in

"default"
"catalog"

node_labels?array<string>|null

profile_stages?Profile Stages

Defaultfalse

query*Query

rerank?|

none or plugin:. Unknown plugin names return 400.

target?string|null

Response Body

`application/json`

curl -X POST "https://example.com/retrieve/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'

{  "channel_lists": {    "property1": [      "string"    ],    "property2": [      "string"    ]  },  "facets": {    "property1": {      "property1": 0,      "property2": 0    },    "property2": {      "property1": 0,      "property2": 0    }  },  "hits": [    {      "channel": "string",      "extras": {},      "id": "string",      "labels": [        "string"      ],      "node_id": "string",      "score": 0,      "scores": {        "bm25": 0,        "cc": 0,        "dense": 0,        "graph": 0,        "personalize": 0,        "plugin": {          "property1": 0,          "property2": 0        },        "rerank": 0,        "rrf": 0      },      "snippet": "string"    }  ],  "node_ids": [    "string"  ],  "stage_timings": {}}

Get Structured Data List

Get a list of structured data.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

types?string|null

query_text?string|null

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/structured-data"

{  "count": 0,  "data": [    {      "brain_version": "0.0.0",      "data": {},      "id": "string",      "inserted_at": "2019-08-24T14:15:22Z",      "metadata": {},      "types": [        "string"      ]    }  ],  "message": "string",  "total": 0}

Get Structured Data Types

Get all unique types from structured data.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/structured-data/types"

{  "count": 0,  "message": "string",  "types": [    "string"  ]}

Get Structured Data By Id

Get structured data by ID.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

`application/json`

curl -X GET "https://example.com/retrieve/structured-data/string"

{  "data": {    "brain_version": "0.0.0",    "data": {},    "id": "string",    "inserted_at": "2019-08-24T14:15:22Z",    "metadata": {},    "types": [      "string"    ]  },  "message": "string"}

Get Text Chunks

Get text chunks by a query text and optional metadata equality filters.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

query_text?string|null

metadata_eq?string|null

order?Order

Default"desc"

Value in

"asc"
"desc"

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/text-chunks"

{  "data": [    {      "brain_version": "0.0.0",      "id": "string",      "inserted_at": "2019-08-24T14:15:22Z",      "metadata": {},      "text": "string"    }  ],  "message": "string",  "total": 0}

Get Vector Stores

List available vector store names and dimensions.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/vectors/stores"

{  "stores": [    {      "dimension": 0,      "name": "string"    }  ]}

Get Vectors List

List vectors in a store with pagination.

Authorization

BrainPAT<token>

BrainAPI personal access token.

In: header

Path Parameters

store*Store

Query Parameters

limit?Limit

Default10

skip?Skip

Default0

include_embeddings?Include Embeddings

Defaultfalse

Header Parameters

X-Brain-ID?string

Preferred brain scope. Query/body/multipart fallbacks remain supported.

Response Body

`application/json`

curl -X GET "https://example.com/retrieve/vectors/string"

{  "message": "string",  "store": "string",  "total": 0,  "vectors": [    {      "distance": 0,      "embeddings": [        0      ],      "id": "string",      "metadata": {}    }  ]}

BrainAPI Retrieve API

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

405application/json

406application/json

422application/json

429application/json

500application/json

503application/json

200application/json

400application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`