Query Knowledge

Query Cerebe's Knowledge Graph to find entities, relationships, and facts. Supports natural language queries with configurable traversal depth and filtering.

Endpoint

POST /api/v1/knowledge/query

Request Body

Parameter	Type	Required	Description
`query`	`string`	Yes	Natural language or structured query
`entity_id`	`string`	No	Starting entity for graph traversal
`entity_type`	`string`	No	Filter results by entity type
`relationship_types`	`string[]`	No	Filter by specific relationship types
`depth`	`integer`	No	Maximum traversal depth, 1-5 (default: 2)
`limit`	`integer`	No	Maximum results, 1-100 (default: 20)

Examples

from cerebe import AsyncCerebe

client = AsyncCerebe(api_key="ck_live_...")

results = await client.knowledge.query(
    query="Who does Alice mentor?",
    depth=2,
    limit=10,
)

for entity in results.entities:
    print(f"{entity.name} ({entity.entity_type})")

for rel in results.relationships:
    print(f"{rel.source_id} --[{rel.relationship_type}]--> {rel.target_id}")

import Cerebe from '@cerebe/sdk'

const client = new Cerebe({ apiKey: 'ck_live_...' })

const results = await client.knowledge.query({
  query: 'Who does Alice mentor?',
  depth: 2,
  limit: 10,
})

for (const entity of results.entities) {
  console.log(`${entity.name} (${entity.entityType})`)
}

for (const rel of results.relationships) {
  console.log(`${rel.sourceId} --[${rel.relationshipType}]--> ${rel.targetId}`)
}

curl -X POST https://api.cerebe.ai/api/v1/knowledge/query \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Who does Alice mentor?",
    "depth": 2,
    "limit": 10
  }'

Response

{
  "entities": [
    {
      "id": "ent_abc123",
      "name": "Alice mentors Bob",
      "entity_type": "fact",
      "properties": null,
      "created_at": "2025-03-07T14:30:00Z"
    }
  ],
  "relationships": [],
  "total": 1
}

Entity Object

Field	Type	Description
`id`	`string`	Unique entity identifier
`name`	`string`	Entity name or fact description
`entity_type`	`string`	Type classification (e.g., `person`, `organization`, `fact`)
`properties`	`object`	Additional entity properties
`created_at`	`string`	ISO-8601 creation timestamp

Relationship Object

Field	Type	Description
`source_id`	`string`	Source entity ID
`target_id`	`string`	Target entity ID
`relationship_type`	`string`	Type of relationship
`properties`	`object`	Relationship properties
`valid_from`	`string`	When this relationship became true
`valid_to`	`string`	When this relationship ended (null if still active)

Temporal Queries

The knowledge graph is temporal --- relationships have valid_from and valid_to fields. This enables point-in-time queries:

# Who was on the team in January?
results = await client.knowledge.query(
    query="team members",
    entity_id="team_alpha",
    depth=1,
)

Error Responses

Status	Description
`401`	Missing or invalid API key
`503`	Knowledge graph service unavailable

Next Steps

Ingest Knowledge — Add content to the graph
Knowledge Overview — Full guide to the Knowledge Graph

Query Knowledge

On this page