Knowledge Graph

Each knowledge base can have an automatically extracted knowledge graph containing entities (people, concepts, products, etc.) and relationships between them. The graph enhances search quality and provides structured context to agents.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

This endpoint incurs provider cost and records a billing event via record_external_cost_event(). Credits are deducted from the organization’s wallet based on the configured margin multiplier.

List Entities

Get a paginated, filterable list of entities in the knowledge base graph.

Path Parameters

string

required

KB UUID.

Query Parameters

string

Filter by entity type (e.g., person, concept, product, organization).

string

Full-text search across entity names and aliases.

string

Filter to entities from a specific document.

number

default:"100"

Maximum results.

number

default:"0"

Pagination offset.

Response (200)

object[]

Array of entity objects.

Show Entity object

string

Entity UUID.

string

Canonical entity name.

string

Entity type.

string[]

Alternative names and spellings.

number

Number of times referenced across documents.

string[]

Documents where this entity appears.

string

ISO 8601 timestamp.

number

Total entity count matching filters.

curl "https://your-domain.com/api/knowledge/kb/KB_ID/graph/entities?\
type=person&limit=50" \
  -H "Authorization: Bearer $TOKEN"

const params = new URLSearchParams({ type: "person", limit: "50" });
const response = await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/graph/entities?${params}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const { entities, total } = await response.json();

Get Entity Detail

Get a single entity with its connected entities and relationships (1-hop neighborhood).

Path Parameters

string

required

KB UUID.

string

required

Entity UUID.

Response (200)

object

The requested entity with full details.

object[]

Entities connected by relationships.

object[]

All relationships involving this entity.

Show Relationship object

string

Relationship UUID.

string

Source entity UUID.

string

Target entity UUID.

string

Relationship type (e.g., works_at, related_to, part_of).

number

Relationship strength (0-1).

string

Source document UUID.

Rename Entity

Rename an entity. The old name is automatically preserved as an alias.

Path Parameters

string

required

KB UUID.

string

required

Entity UUID.

Request Body

string

required

New canonical name for the entity.

Response (200)

object

Updated entity object.

Merge Entities

Merge multiple entities into a canonical entity. The target entity absorbs the names (as aliases) and relationships of the merged entities. Use this to resolve duplicates.

Path Parameters

string

required

KB UUID.

string

required

Canonical (target) entity UUID — the entity that will absorb others.

Request Body

string[]

required

Array of entity UUIDs to merge into the canonical entity. These entities will be deleted after merging.

Response (200)

string

Confirmation with merge count.

string

The surviving entity UUID.

number

Number of entities merged.

curl

curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/graph/entities/ENTITY_ID/merge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mergeEntityIds": ["dup-entity-1", "dup-entity-2"]
  }'

Delete Entity

Delete an entity and all of its relationships.

Path Parameters

string

required

KB UUID.

string

required

Entity UUID.

Response (204)

No content on success.

Graph Stats

Get aggregate statistics about the knowledge graph (entity counts by type, relationship counts, etc.).

Path Parameters

string

required

KB UUID.

Response (200)

object

Graph statistics.

Show Stats

number

Total entity count.

number

Total relationship count.

object

Count per entity type.

Graph Optimization

The optimization endpoints help improve graph quality by detecting and resolving duplicate entities, suggesting merges, and cleaning up the graph.

Get Optimization Stats

Get counts of optimization suggestions by type and status.

Path Parameters

string

required

KB UUID.

List Optimization Suggestions

Get paginated list of optimization suggestions (e.g., merge duplicates, rename inconsistent entities).

Path Parameters

string

required

KB UUID.

Query Parameters

string

Filter by status: pending, approved, rejected, applied.

string

Filter by suggestion type.

number

Maximum results.

number

Pagination offset.

Generate Suggestions

Trigger asynchronous generation of optimization suggestions for the knowledge graph. Queues a background job.

Path Parameters

string

required

KB UUID.

Response (200)

string

“Suggestion generation started”

string

Background job ID for tracking.

AI Auto-Resolve Suggestions

Use AI to automatically approve or reject pending optimization suggestions. Queues a background job that evaluates each suggestion using an LLM.

Path Parameters

string

required

KB UUID.

Response (200)

string

“AI resolve started”

string

Background job ID.

Update Suggestion Status

Manually approve or reject a single optimization suggestion.

Path Parameters

string

required

KB UUID.

string

required

Suggestion UUID.

Request Body

string

required

New status: approved or rejected.

Response (200)

object

Updated suggestion object.

Apply Approved Suggestions

Apply a set of approved suggestions to the knowledge graph (execute merges, renames, etc.).

Path Parameters

string

required

KB UUID.

Request Body

string[]

required

Array of approved suggestion UUIDs to apply.

Response (200)

number

Number of suggestions successfully applied.

number

Number of suggestions that failed to apply.

string[]

Error messages for failed suggestions.

# 1. Generate suggestions
curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/graph/optimize/generate \
  -H "Authorization: Bearer $TOKEN"

# 2. AI auto-resolve
curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/graph/optimize/ai-resolve \
  -H "Authorization: Bearer $TOKEN"

# 3. Apply approved suggestions
curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/graph/optimize/apply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"suggestionIds": ["suggestion-1", "suggestion-2"]}'

// 1. Generate suggestions
await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/graph/optimize/generate`,
  { method: "POST", headers: { Authorization: `Bearer ${token}` } }
);

// 2. AI auto-resolve
await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/graph/optimize/ai-resolve`,
  { method: "POST", headers: { Authorization: `Bearer ${token}` } }
);

// 3. Get approved suggestions
const { suggestions } = await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/graph/optimize/suggestions?status=approved`,
  { headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());

// 4. Apply them
await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/graph/optimize/apply`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      suggestionIds: suggestions.map(s => s.id),
    }),
  }
);

Pinned Entities

Get Pinned Entities

Get user-defined known entities that are used to seed future graph extractions.

Update Pinned Entities

Set the list of known entities for a KB. These entities are provided to the extraction LLM as context, improving entity recognition consistency across documents.

​Knowledge Graph

​List Entities

​Path Parameters

​Query Parameters

​Response (200)

​Get Entity Detail

​Path Parameters

​Response (200)

​Rename Entity

​Path Parameters

​Request Body

​Response (200)

​Merge Entities

​Path Parameters

​Request Body

​Response (200)

​Delete Entity

​Path Parameters

​Response (204)

​Graph Stats

​Path Parameters

​Response (200)

​Graph Optimization

​Get Optimization Stats

​Path Parameters

​List Optimization Suggestions

​Path Parameters

​Query Parameters

​Generate Suggestions

​Path Parameters

​Response (200)

​AI Auto-Resolve Suggestions

​Path Parameters

​Response (200)

​Update Suggestion Status

​Path Parameters

​Request Body

​Response (200)

​Apply Approved Suggestions

​Path Parameters

​Request Body

​Response (200)

​Pinned Entities

​Get Pinned Entities

​Update Pinned Entities

Knowledge Graph

List Entities

Path Parameters

Query Parameters

Response (200)

Get Entity Detail

Path Parameters

Response (200)

Rename Entity

Path Parameters

Request Body

Response (200)

Merge Entities

Path Parameters

Request Body

Response (200)

Delete Entity

Path Parameters

Response (204)

Graph Stats

Path Parameters

Response (200)

Graph Optimization

Get Optimization Stats

Path Parameters

List Optimization Suggestions

Path Parameters

Query Parameters

Generate Suggestions

Path Parameters

Response (200)

AI Auto-Resolve Suggestions

Path Parameters

Response (200)

Update Suggestion Status

Path Parameters

Request Body

Response (200)

Apply Approved Suggestions

Path Parameters

Request Body

Response (200)

Pinned Entities

Get Pinned Entities

Update Pinned Entities