Cortex API

Knowledge Graph

Endpoint

Entity and relationship operations

GraphRAG status

GET

http://localhost:8000

/api/graph/status

Get knowledge graph statistics

GraphRAG status › Responses

200

Status retrieved

enabled

boolean

entity_count

integer

relationship_count

integer

community_count

integer

last_extraction

string · date-time

GET/api/graph/status

curl --request GET \
  --url http://localhost:8000/api/graph/status

shell

Example Responses

{
  "enabled": true,
  "entity_count": 0,
  "relationship_count": 0,
  "community_count": 0,
  "last_extraction": "2024-08-25T15:00:00Z"
}

json

application/json

Get graph visualization data

GET

http://localhost:8000

/api/graph/visualization

Get graph visualization data › query Parameters

limit

integer

Default: 100

include_neighbors

boolean

Default: true

collection_id

string

Get graph visualization data › Responses

200

Graph data retrieved

object[]

GET/api/graph/visualization

curl --request GET \
  --url http://localhost:8000/api/graph/visualization

shell

Example Responses

{
  "nodes": [
    {
      "id": "id",
      "name": "name",
      "type": "type",
      "description": "description",
      "mention_count": 0
    }
  ],
  "edges": [
    {
      "source": "source",
      "target": "target",
      "type": "type",
      "description": "description"
    }
  ]
}

json

application/json

List entities

GET

http://localhost:8000

/api/graph/entities

List entities › query Parameters

skip

integer

Default: 0

limit

integer

Default: 50

List entities › Responses

200

Entities retrieved

object[]

total

integer

GET/api/graph/entities

curl --request GET \
  --url http://localhost:8000/api/graph/entities

shell

Example Responses

{
  "entities": [
    {
      "name": "name",
      "type": "type",
      "description": "description",
      "mention_count": 0
    }
  ],
  "total": 0
}

json

application/json

Delete ALL entities

DELETE

http://localhost:8000

/api/graph/entities

Delete ALL entities and their connections (including chunk MENTIONS links) from the knowledge graph. Requires manage permission. Useful before re-running the full extraction pipeline.

Delete ALL entities › Responses

200

Entities deleted

entities_deleted

integer

Number of entities deleted

DELETE/api/graph/entities

curl --request DELETE \
  --url http://localhost:8000/api/graph/entities

shell

Example Responses

{
  "entities_deleted": 0
}

json

application/json

List entity types

GET

http://localhost:8000

/api/graph/entity-types

Get all distinct entity types in the knowledge graph. For restricted API keys, results are scoped to accessible collections.

List entity types › Responses

200

Entity types retrieved

types

string[]

GET/api/graph/entity-types

curl --request GET \
  --url http://localhost:8000/api/graph/entity-types

shell

Example Responses

{
  "types": [
    "string"
  ]
}

json

application/json

List relationship types

GET

http://localhost:8000

/api/graph/relationship-types

Get all distinct relationship types in the knowledge graph. For restricted API keys, results are scoped to accessible collections.

List relationship types › Responses

200

Relationship types retrieved

types

string[]

GET/api/graph/relationship-types

curl --request GET \
  --url http://localhost:8000/api/graph/relationship-types

shell

Example Responses

{
  "types": [
    "string"
  ]
}

json

application/json

Get entity details

GET

http://localhost:8000

/api/graph/entity/{name}

Get entity details › path Parameters

name

string · required

Get entity details › Responses

200

Entity details retrieved

name

string

type

string

description

string

mention_count

integer

documents

string[]

first_seen

string · date-time

GET/api/graph/entity/{name}

curl --request GET \
  --url http://localhost:8000/api/graph/entity/:name

shell

Example Responses

{
  "name": "name",
  "type": "type",
  "description": "description",
  "mention_count": 0,
  "documents": [
    "string"
  ],
  "first_seen": "2024-08-25T15:00:00Z"
}

json

application/json

Update entity

PATCH

http://localhost:8000

/api/graph/entity/{name}

Update an entity's name and/or description. Name changes add the old name to aliases. Rejects duplicate names.

Update entity › path Parameters

name

string · required

Update entity › Request Body

name

string

New entity name

description

string

New entity description

Update entity › Responses

Entity updated

name

string

type

string

description

string

aliases

string[]

PATCH/api/graph/entity/{name}

curl --request PATCH \
  --url http://localhost:8000/api/graph/entity/:name \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "description": "description"
}
'

shell

Example Request Body

{
  "name": "name",
  "description": "description"
}

json

Example Responses

{
  "name": "name",
  "type": "type",
  "description": "description",
  "aliases": [
    "string"
  ]
}

json

application/json

Get entity relationships

GET

http://localhost:8000

/api/graph/entity/{name}/relationships

Get entity relationships › path Parameters

name

string · required

Get entity relationships › query Parameters

max_hops

integer

Default: 2

Get entity relationships › Responses

200

Relationships retrieved

entity

string

object[]

GET/api/graph/entity/{name}/relationships

curl --request GET \
  --url http://localhost:8000/api/graph/entity/:name/relationships

shell

Example Responses

{
  "entity": "entity",
  "relationships": [
    {
      "target": "target",
      "type": "type",
      "description": "description",
      "hop": 0
    }
  ]
}

json

application/json

Get subgraph

POST

http://localhost:8000

/api/graph/subgraph

Get a focused subgraph for specific entities

Get subgraph › Request Body

entity_names

string[] · required

max_hops

integer

Default: 2

limit

integer

Default: 50

Get subgraph › Responses

200

Subgraph retrieved

object[]

POST/api/graph/subgraph

curl --request POST \
  --url http://localhost:8000/api/graph/subgraph \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity_names": [
    "string"
  ],
  "max_hops": 0,
  "limit": 0
}
'

shell

Example Request Body

{
  "entity_names": [
    "string"
  ],
  "max_hops": 0,
  "limit": 0
}

json

Example Responses

{
  "nodes": [
    {
      "id": "id",
      "name": "name",
      "type": "type",
      "description": "description",
      "mention_count": 0
    }
  ],
  "edges": [
    {
      "source": "source",
      "target": "target",
      "type": "type",
      "description": "description"
    }
  ]
}

json

application/json

Search entities

GET

http://localhost:8000

/api/graph/search

Search entities › query Parameters

query

string · required

Search entities › Responses

200

Entities found

object[]

total

integer

GET/api/graph/search

curl --request GET \
  --url 'http://localhost:8000/api/graph/search?query=%3Cstring%3E'

shell

Example Responses

{
  "entities": [
    {
      "name": "name",
      "type": "type",
      "description": "description",
      "mention_count": 0
    }
  ],
  "total": 0
}

json

application/json

Find duplicate entity candidates

GET

http://localhost:8000

/api/entities/duplicates

Returns groups of entities that are potential duplicates based on name similarity. Uses fuzzy string matching to identify entities that likely refer to the same thing but were not caught by automatic resolution during extraction. One scan runs at a time (single-flight); identical requests join the running scan. On large graphs the scan may outlast the inline wait window, in which case the response is 202 with a progress fraction — poll the same URL (without refresh) until it returns status "complete". Completed results are cached server-side; entity merges invalidate the cache.

Find duplicate entity candidates › query Parameters

threshold

number · min: 0.5 · max: 1

Similarity threshold for duplicate detection (0.5 to 1.0)

Default: 0.85

limit

integer

Maximum number of duplicate groups to return

Default: 50

refresh

boolean

Bypass the cached result and force a fresh scan

Default: false

Find duplicate entity candidates › Responses

Duplicate candidates retrieved (status "complete")

status

string · enum

Always "complete" on a 200 response

Enum values:

complete

cached

boolean

True when served from the server-side scan cache

object[]

total_groups

integer

Total number of duplicate groups found

threshold

number

Similarity threshold used for detection

GET/api/entities/duplicates

curl --request GET \
  --url http://localhost:8000/api/entities/duplicates

shell

Example Responses

{
  "status": "complete",
  "cached": true,
  "groups": [
    {
      "canonical": "canonical",
      "duplicates": [
        {
          "name": "name",
          "type": "type",
          "similarity": 0,
          "mention_count": 0
        }
      ],
      "similarity": 0
    }
  ],
  "total_groups": 0,
  "threshold": 0
}

json

application/json

Merge duplicate entities

POST

http://localhost:8000

/api/entities/merge

Merges one or more duplicate entities into a canonical entity. All relationships, chunk mentions, and community memberships from the merged entities are transferred to the canonical entity. Merged entities are removed from the graph.

Merge duplicate entities › Request Body

canonical

string · required

The name of the entity to keep (canonical/primary entity)

merge

string[] · required

List of entity names to merge into the canonical entity

Merge duplicate entities › Responses

Entities merged successfully

canonical

string

The canonical entity name that was kept

merged

string[]

Entity names that were merged and removed

relationships_transferred

integer

Number of relationships moved to the canonical entity

mentions_transferred

integer

Number of chunk mentions moved to the canonical entity

aliases_added

string[]

Aliases added to the canonical entity from merged entities

POST/api/entities/merge

curl --request POST \
  --url http://localhost:8000/api/entities/merge \
  --header 'Content-Type: application/json' \
  --data '
{
  "canonical": "canonical",
  "merge": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "canonical": "canonical",
  "merge": [
    "string"
  ]
}

json

Example Responses

{
  "canonical": "canonical",
  "merged": [
    "string"
  ],
  "relationships_transferred": 0,
  "mentions_transferred": 0,
  "aliases_added": [
    "string"
  ]
}

json

application/json

Get entity merge history

GET

http://localhost:8000

/api/entities/merge-history

Returns a chronological log of entity merge operations, including which entities were merged into which canonical entity and when.

Get entity merge history › query Parameters

limit

integer

Maximum number of history entries to return

Default: 50

Get entity merge history › Responses

200

Merge history retrieved

object[]

total

integer

Total number of merge history entries

GET/api/entities/merge-history

curl --request GET \
  --url http://localhost:8000/api/entities/merge-history

shell

Example Responses

{
  "entries": [
    {
      "canonical": "canonical",
      "merged": [
        "string"
      ],
      "relationships_transferred": 0,
      "mentions_transferred": 0,
      "merged_at": "2024-08-25T15:00:00Z"
    }
  ],
  "total": 0
}

json

application/json

List relationships

GET

http://localhost:8000

/api/graph/relationships

List relationships between entities with server-side pagination and search. Excludes internal edge types (MENTIONS, HAS_MEMBER, FROM_DOCUMENT, CO_MENTION). For restricted API keys, results are scoped to accessible collections.

List relationships › query Parameters

rel_type

string

Filter by relationship type

search

string

Search in source, target, and description

skip

integer

Default: 0

limit

integer · min: 1 · max: 1000

Default: 50

List relationships › Responses

200

Relationships retrieved

object[]

total

integer

Total number of matching relationships

GET/api/graph/relationships

curl --request GET \
  --url http://localhost:8000/api/graph/relationships

shell

Example Responses

{
  "relationships": [
    {
      "source": "source",
      "target": "target",
      "type": "type",
      "description": "description",
      "weight": 0
    }
  ],
  "total": 0
}

json

application/json

Delete all relationships

DELETE

http://localhost:8000

/api/graph/relationships

Delete ALL relationships between entities (excluding chunk MENTIONS links). Useful before re-running relationship analysis with different settings or models.

Delete all relationships › Responses

200

Relationships deleted

relationships_deleted

integer

Number of relationships deleted

DELETE/api/graph/relationships

curl --request DELETE \
  --url http://localhost:8000/api/graph/relationships

shell

Example Responses

{
  "relationships_deleted": 0
}

json

application/json

Analyze cross-document relations

POST

http://localhost:8000

/api/graph/relationships/analyze

Triggers Phase B of the extraction pipeline. The main (large) model analyzes all entities and discovers cross-document relations. Run this after batch document processing to build the relationship graph.

Analyze cross-document relations › query Parameters

collection_id

string

Scope to a specific collection (None = global)

scope

string · enum

'recent' for new entities, 'full' for all

Enum values:

recent

full

Default: full

Analyze cross-document relations › Responses

200

Analysis task started

task_id

string

status

string

message

string

tip

string

POST/api/graph/relationships/analyze

curl --request POST \
  --url http://localhost:8000/api/graph/relationships/analyze

shell

Example Responses

{
  "task_id": "task_id",
  "status": "status",
  "message": "message",
  "tip": "tip"
}

json

application/json

Clean up orphaned entities and communities

POST

http://localhost:8000

/api/cleanup/orphaned-entities

Remove entities not connected to any document chunks and communities with no member entities. Use this after bulk document deletion to clean up stale graph data.

Clean up orphaned entities and communities › Responses

200

Cleanup completed

message

string

orphaned_entities_removed

integer

orphaned_communities_removed

integer

POST/api/cleanup/orphaned-entities

curl --request POST \
  --url http://localhost:8000/api/cleanup/orphaned-entities

shell

Example Responses

{
  "message": "message",
  "orphaned_entities_removed": 0,
  "orphaned_communities_removed": 0
}

json

application/json

Ask AI Collections