Cortex API

Schemas

HealthResponse

status

string

neo4j

string

version

string

StatsResponse

document_count

integer

chunk_count

integer

entity_count

integer

relationship_count

integer

per_chunk_relationship_count

integer

Relations discovered in Step 1 (per-chunk extraction)

collection_count

integer

Document

id

string

filename

string

file_type

string

file_size

integer

upload_date

string · date-time

processing_status

string · enum

Enum values:

pending

processing

extracting_entities

completed

failed

chunk_count

integer

collection_id

string

source

string

Origin of the document (e.g. 'upload', 'custom_input', or a custom source set via API)

DocumentList

object[]

total

integer

DocumentContent

id

string

filename

string

object[]

CustomInputCreate

input_type

string · enum · required

Enum values:

text

markdown

content

string · required

answer

string

Required for Q&A type

collection_id

string

source

string

Custom source identifier (defaults to 'custom_input' if not set)

CustomInputResponse

id

string

input_type

string

filename

string

source

string

Origin of the document

created_at

string · date-time

CustomInputItem

id

string

input_type

string

content

string

answer

string

filename

string

collection_id

string

created_at

string · date-time

SearchRequest

query

string · required

top_k

integer

Default: 10

collection_id

string

use_hybrid

boolean

Default: true

use_reranking

boolean

Default: true

SearchResponse

object[]

total

integer

query

string

search_time_ms

integer

AskRequest

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

AskResponse

answer

string

object[]

object

retrieval_stats

object

GraphStatus

enabled

boolean

entity_count

integer

relationship_count

integer

community_count

integer

last_extraction

string · date-time

GraphVisualization

object[]

EntityList

object[]

total

integer

EntityDetails

name

string

type

string

description

string

mention_count

integer

documents

string[]

first_seen

string · date-time

EntityRelationships

entity

string

object[]

CollectionCreate

name

string · required

description

string

CollectionUpdate

name

string

New collection name (1-100 characters)

description

string

New collection description (max 500 characters)

Collection

id

string

name

string

description

string

created_at

string · date-time

CollectionDetails

id

string

name

string

description

string

document_count

integer

entity_count

integer

relationship_count

integer

community_count

integer

created_at

string · date-time

updated_at

string · date-time

CollectionList

object[]

CommunityList

object[]

total

integer

CommunityDetails

id

integer

name

string

summary

string

object[]

TaskProgress

task_id

string

status

string · enum

Enum values:

pending

running

completed

failed

progress

integer

message

string

created_at

string · date-time

completed_at

string · date-time

TaskStartResponse

task_id

string

status

string

ApiKeyCreate

name

string · required

permissions

string[] · required

Enum values:

read

manage

admin

ApiKeyUpdate

name

string

permissions

string[]

Enum values:

read

manage

admin

ApiKey

id

string

name

string

key_prefix

string

permissions

string[]

status

string · enum

Enum values:

active

revoked

created_at

string · date-time

last_used_at

string · date-time

ApiKeyCreated

id

string

name

string

key

string

Full API key (only shown once)

permissions

string[]

created_at

string · date-time

ApiKeyList

object[]

DuplicateGroup

canonical

string

The entity name with the highest mention count in this group

object[]

List of entities similar to the canonical entity

similarity

number

Average similarity score within this group

DuplicateCandidates

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

EntityMergeRequest

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

EntityMergeResponse

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

MergeHistoryEntry

canonical

string

The canonical entity name

merged

string[]

Entity names that were merged

relationships_transferred

integer

mentions_transferred

integer

merged_at

string · date-time

When the merge was performed

MergeHistoryResponse

object[]

total

integer

Total number of merge history entries

SystemResetRequest

delete_documents

boolean

Delete all documents, chunks, entities, relationships, communities, merge history, and system metadata

Default: true

delete_uploaded_files

boolean

Delete uploaded files from disk

Default: true

delete_custom_inputs

boolean

Delete custom input files from disk

Default: true

delete_collections

boolean

Delete all non-default collections

Default: true

delete_api_keys

boolean

Delete all API keys (dangerous — defaults to false)

Default: false

SystemResetResponse

message

string

Summary message of what was deleted

documents_deleted

integer

Number of documents deleted

entities_removed

integer

Number of entities removed

communities_removed

integer

Number of communities removed

merge_history_deleted

integer

Number of merge history records deleted

system_meta_deleted

integer

Number of system metadata records deleted

collections_deleted

integer

Number of collections deleted

api_keys_deleted

integer

Number of API keys deleted

uploaded_files_deleted

integer

Number of uploaded files deleted

custom_inputs_deleted

integer

Number of custom input files deleted

processing_cancelled

integer

Number of active processing tasks cancelled

LibraryExportManifest

version

string

Export format version

Example: 1.0

export_date

string · date-time

When the export was created

embedding_model

string

Embedding model used by the source instance

embedding_dimension

integer

Embedding vector dimension

object

Counts of exported items

LibraryImportResult

documents_imported

integer

chunks_imported

integer

entities_imported

integer

relationships_imported

integer

communities_imported

integer

collections_imported

integer

files_imported

integer

merge_history_imported

integer

embedding_compatible

boolean

Whether the source and target embedding configs match

warnings

string[]

Any warnings encountered during import (e.g., embedding mismatch)

RelationshipList

object[]

total

integer

Total number of matching relationships

RuntimeSettingsUpdate

Admin-editable runtime setting overrides (persisted, take effect without a restart). All fields optional — only provided fields are updated.

ingestion_injection_scan

boolean | null

Enable/disable the LLM prompt-injection scan on ingested documents (experimental — rejected with 400 unless the instance sets ENABLE_INGESTION_INJECTION_SCAN=true)

prompt_guard

boolean | null

Enable/disable the query-time prompt-guard classifier gate (costs one extra query per guarded ask)

WebImportRequest

urls

string[] · minItems: 1 · required

Absolute http(s) URLs to crawl

collection_id

string

Collection to add the harvested documents to

content_filter

string

crawl4ai filter: 'fit' (readability, default), 'raw', or 'bm25'

query

string

Relevance query (only used by the 'bm25' filter)

WebImportResponse

task_id

string

Background task id to poll for progress

accepted_urls

integer

Number of URLs accepted into the job

message

string

WebDiscoverRequest

url

string · required

Page URL to scan for same-host links

WebDiscoverResponse

source_url

string

domain

string

object[]

GitConnectionCreate

vendor

string · enum · required

Git hosting provider

Enum values:

github

gitlab

gitea

repo_owner

string · required

Repo owner / org / group (or GitLab namespace path)

repo_name

string · required

pat

string · minLength: 8 · required

Personal access token used for clone + API

base_url

string

API base URL for self-hosted GitLab/Gitea (omit for github.com/gitlab.com)

access_level

string · enum

Enum values:

read

read_write

Default: read

branch

string

Branch to sync (defaults to repo default branch)

include_globs

string[]

gitignore-style include patterns (empty = all files)

exclude_globs

string[]

gitignore-style exclude patterns

wiki_enabled

boolean

Also ingest the repo wiki

Default: false

collection_id

string

Target collection for ingested documents

sync_interval_minutes

integer · min: 0

Scheduled-sync interval in minutes (0 = manual only)

Default: 0

GitConnectionUpdate

Partial update of a git connection. PAT is rotated only if provided.

pat

string · minLength: 8

New PAT (rotation); omit to keep existing

access_level

string · enum

Enum values:

read

read_write

branch

string

include_globs

string[]

exclude_globs

string[]

wiki_enabled

boolean

collection_id

string

sync_interval_minutes

integer · min: 0

GitConnectionResponse

Git connection for API responses. PAT is always masked.

id

string

vendor

string · enum

Enum values:

github

gitlab

gitea

base_url

string | null

repo_owner

string

repo_name

string

pat_masked

string

Masked token, e.g. '••••abcd'

access_level

string · enum

Enum values:

read

read_write

branch

string | null

default_branch

string | null

include_globs

string[]

exclude_globs

string[]

wiki_enabled

boolean

collection_id

string | null

sync_interval_minutes

integer

last_synced_sha

string | null

last_synced_at

string | null

next_sync_due

string | null

sync_status

string | null

created_at

string | null

GitConnectionVerifyRequest

vendor

string · enum · required

Enum values:

github

gitlab

gitea

pat

string · minLength: 8 · required

base_url

string

GitVerifyResponse

valid

boolean

login

string | null

Authenticated account/login

message

string | null

GitRepoBrowseItem

owner

string

name

string

full_name

string

default_branch

string | null

private

boolean

web_url

string | null

GitSyncTriggerResponse

task_id

string

connection_id

string

message

string

SkillInstallRequest

Provide exactly one of url or registry_id.

url

string

Direct URL to SKILL.md or ZIP archive

registry_id

string

Registry identifier (namespace/name) from skills.sh

SkillUpdateRequest

enabled

boolean | null

Enable or disable the skill

SkillConfigSaveRequest

values

object · required

Map of variable name to value

APIKeyStats

total_requests

integer

requests_today

integer

requests_this_week

integer

requests_this_month

integer

error_count

integer

last_error_at

string | null · date-time

last_error_message

string | null

endpoint_breakdown

object

Request counts by endpoint category

APIKeyWithStats

API key list item with usage statistics attached.

id

string

name

string

key_prefix

string

permissions

string[]

Enum values:

read

manage

admin

is_active

boolean

created_at

string · date-time

last_used_at

string | null · date-time

created_by

string

collection_scope

string

allowed_collections

string[]

allowed_collection_names

array | null

object

APIKeyUsageDataPoint

date

string

Date in YYYY-MM-DD format

requests

integer

errors

integer

APIKeyUsageHistoryResponse

key_id

string

key_name

string

object[]

period_days

integer

AdminStatsOverview

total_keys

integer

active_keys

integer

total_requests_all_time

integer

total_requests_today

integer

total_requests_this_week

integer

total_requests_this_month

integer

total_errors

integer

most_active_key

string | null

endpoint_breakdown

object

Aggregated endpoint usage across all keys