Cortex API

Admin

Endpoint

API key management, system configuration, library import/export

Get system configuration

GET

http://localhost:8000

/api/admin/config

Returns current system settings (model names, API base URLs, context windows, concurrency settings). No API keys or secrets are exposed.

Get system configuration › Responses

System configuration

openai_model

string

Primary LLM model name

openai_api_base

string

Primary LLM API base URL

extraction_model

string

Entity extraction model name

extraction_api_base

string

Extraction model API base URL

extraction_max_context

integer

Max context window tokens for entity extraction

relationship_model

string

Relationship extraction model name

relationship_api_base

string

Relationship model API base URL

relationship_max_context

integer

Max context window tokens for relationship analysis

concurrent_relations

integer

Concurrent per-chunk relationship extractions per document

parallel_relationship_batches

integer

Relationship analysis batches processed in parallel

vision_model_available

boolean

vision_model

string

vision_api_base

string

vision_max_concurrent

integer

embedding_model

string

embedding_dimension

integer

embedding_api_base

string

embedding_send_dimensions

boolean

GET/api/admin/config

curl --request GET \
  --url http://localhost:8000/api/admin/config

shell

Example Responses

{
  "openai_model": "openai_model",
  "openai_api_base": "openai_api_base",
  "extraction_model": "extraction_model",
  "extraction_api_base": "extraction_api_base",
  "extraction_max_context": 0,
  "relationship_model": "relationship_model",
  "relationship_api_base": "relationship_api_base",
  "relationship_max_context": 0,
  "concurrent_relations": 0,
  "parallel_relationship_batches": 0,
  "vision_model_available": true,
  "vision_model": "vision_model",
  "vision_api_base": "vision_api_base",
  "vision_max_concurrent": 0,
  "embedding_model": "embedding_model",
  "embedding_dimension": 0,
  "embedding_api_base": "embedding_api_base",
  "embedding_send_dimensions": true
}

json

application/json

Update runtime settings

PATCH

http://localhost:8000

/api/admin/config

Update admin-editable runtime settings. Overrides are persisted (over the env defaults) and take effect immediately for new work without a restart. Only provided fields are changed. Returns the full, updated system configuration. Admin-only. The experimental ingestion_injection_scan field is rejected with 400 unless ENABLE_INGESTION_INJECTION_SCAN=true is set on the instance.

Update runtime settings › Request Body

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)

Update runtime settings › Responses

Updated system configuration

The full system configuration after applying the update (same shape as GET /api/admin/config)

PATCH/api/admin/config

curl --request PATCH \
  --url http://localhost:8000/api/admin/config \
  --header 'Content-Type: application/json' \
  --data '
{
  "ingestion_injection_scan": {},
  "prompt_guard": {}
}
'

shell

Example Request Body

{
  "ingestion_injection_scan": {},
  "prompt_guard": {}
}

json

Example Responses

{}

json

application/json

List API keys

GET

http://localhost:8000

/api/admin/api-keys

List API keys › Responses

200

API keys retrieved

object[]

GET/api/admin/api-keys

curl --request GET \
  --url http://localhost:8000/api/admin/api-keys

shell

Example Responses

{
  "api_keys": [
    {
      "id": "id",
      "name": "name",
      "key_prefix": "key_prefix",
      "permissions": [
        "string"
      ],
      "status": "active",
      "created_at": "2024-08-25T15:00:00Z",
      "last_used_at": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

Create API key

POST

http://localhost:8000

/api/admin/api-keys

Create API key › Request Body

name

string · required

permissions

string[] · required

Enum values:

read

manage

admin

Create API key › Responses

200

API key created

id

string

name

string

key

string

Full API key (only shown once)

permissions

string[]

created_at

string · date-time

POST/api/admin/api-keys

curl --request POST \
  --url http://localhost:8000/api/admin/api-keys \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "permissions": [
    "read"
  ]
}
'

shell

Example Request Body

{
  "name": "name",
  "permissions": [
    "read"
  ]
}

json

Example Responses

{
  "id": "id",
  "name": "name",
  "key": "key",
  "permissions": [
    "string"
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Get API key details

GET

http://localhost:8000

/api/admin/api-keys/{key_id}

Get API key details › path Parameters

key_id

string · required

Get API key details › Responses

200

API key retrieved

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

GET/api/admin/api-keys/{key_id}

curl --request GET \
  --url http://localhost:8000/api/admin/api-keys/:key_id

shell

Example Responses

{
  "id": "id",
  "name": "name",
  "key_prefix": "key_prefix",
  "permissions": [
    "string"
  ],
  "status": "active",
  "created_at": "2024-08-25T15:00:00Z",
  "last_used_at": "2024-08-25T15:00:00Z"
}

json

application/json

Delete API key

DELETE

http://localhost:8000

/api/admin/api-keys/{key_id}

Delete API key › path Parameters

key_id

string · required

Delete API key › Responses

200

API key deleted

No data returned

DELETE/api/admin/api-keys/{key_id}

curl --request DELETE \
  --url http://localhost:8000/api/admin/api-keys/:key_id

shell

Example Responses

No example specified for this content type

Update API key

PATCH

http://localhost:8000

/api/admin/api-keys/{key_id}

Update API key › path Parameters

key_id

string · required

Update API key › Request Body

name

string

permissions

string[]

Enum values:

read

manage

admin

Update API key › Responses

200

API key updated

No data returned

PATCH/api/admin/api-keys/{key_id}

curl --request PATCH \
  --url http://localhost:8000/api/admin/api-keys/:key_id \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "name",
  "permissions": [
    "read"
  ]
}
'

shell

Example Request Body

{
  "name": "name",
  "permissions": [
    "read"
  ]
}

json

Example Responses

No example specified for this content type

Revoke API key

POST

http://localhost:8000

/api/admin/api-keys/{key_id}/revoke

Revoke API key › path Parameters

key_id

string · required

Revoke API key › Responses

200

API key revoked

No data returned

POST/api/admin/api-keys/{key_id}/revoke

curl --request POST \
  --url http://localhost:8000/api/admin/api-keys/:key_id/revoke

shell

Example Responses

No example specified for this content type

Activate API key

POST

http://localhost:8000

/api/admin/api-keys/{key_id}/activate

Activate API key › path Parameters

key_id

string · required

Activate API key › Responses

200

API key activated

No data returned

POST/api/admin/api-keys/{key_id}/activate

curl --request POST \
  --url http://localhost:8000/api/admin/api-keys/:key_id/activate

shell

Example Responses

No example specified for this content type

System reset

POST

http://localhost:8000

/api/admin/reset

Selectively delete data from the system. This is a destructive operation that cannot be undone. When documents are deleted, associated data is also cleaned up: merge history (deduplication audit trail), system metadata (staleness timestamps), and all graph data (entities, relationships, communities).

System reset › Request Body

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

System reset › Responses

200

System reset completed

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

POST/api/admin/reset

curl --request POST \
  --url http://localhost:8000/api/admin/reset \
  --header 'Content-Type: application/json' \
  --data '
{
  "delete_documents": true,
  "delete_uploaded_files": true,
  "delete_custom_inputs": true,
  "delete_collections": true,
  "delete_api_keys": true
}
'

shell

Example Request Body

{
  "delete_documents": true,
  "delete_uploaded_files": true,
  "delete_custom_inputs": true,
  "delete_collections": true,
  "delete_api_keys": true
}

json

Example Responses

{
  "message": "message",
  "documents_deleted": 0,
  "entities_removed": 0,
  "communities_removed": 0,
  "merge_history_deleted": 0,
  "system_meta_deleted": 0,
  "collections_deleted": 0,
  "api_keys_deleted": 0,
  "uploaded_files_deleted": 0,
  "custom_inputs_deleted": 0,
  "processing_cancelled": 0
}

json

application/json

Start library export

POST

http://localhost:8000

/api/admin/export

Start a background task that exports the entire library (documents, knowledge graph, embeddings, communities, collections, and all metadata) as a ZIP64 archive. Only one export or import can run at a time.

Start library export › Responses

Export task started

task_id

string

Task ID for polling progress

status

string

message

string

POST/api/admin/export

curl --request POST \
  --url http://localhost:8000/api/admin/export

shell

Example Responses

{
  "task_id": "task_id",
  "status": "pending",
  "message": "Export started"
}

json

application/json

Download library export

GET

http://localhost:8000

/api/admin/export/{task_id}/download

Download a completed library export as a ZIP file. The export must have completed successfully (poll the task status first). Streams the file in 1MB chunks.

Download library export › path Parameters

task_id

string · required

The export task ID

Download library export › Responses

ZIP file stream

string

GET/api/admin/export/{task_id}/download

curl --request GET \
  --url http://localhost:8000/api/admin/export/:task_id/download

shell

Example Responses

string

plain

application/zip

Import library from export archive

POST

http://localhost:8000

/api/admin/import

Upload a library export ZIP and start a background import task. Two modes are available:

clean (default): Requires the target instance to be empty
replace: Automatically wipes all existing data before importing

The import validates the archive structure, checks embedding model compatibility, and restores all nodes, relationships, and files.

Import library from export archive › query Parameters

mode

string · enum

Import mode

Enum values:

clean

replace

Default: clean

Import library from export archive › Request Body

file

string · required

The export ZIP file

Import library from export archive › Responses

Import task started

task_id

string

Task ID for polling progress

status

string

message

string

POST/api/admin/import

curl --request POST \
  --url http://localhost:8000/api/admin/import \
  --header 'Content-Type: multipart/form-data' \
  --form file=file

shell

Example Request Body

{
  "file": "file"
}

json

Example Responses

{
  "task_id": "task_id",
  "status": "pending",
  "message": "Import started (mode: clean)"
}

json

application/json

Start a chunked import upload session

POST

http://localhost:8000

/api/admin/import/upload/start

Open a chunked upload session for a library export ZIP. Use this instead of the single-request /api/admin/import when uploading through reverse proxies with body-read timeouts (e.g. Traefik v3 defaults to 60s): each chunk is a short independent request. The web UI always uses this flow.

Start a chunked import upload session › Request Body

total_size

integer · required

Total ZIP size in bytes

filename

string

Start a chunked import upload session › Responses

Upload session created

upload_id

string

received

integer

POST/api/admin/import/upload/start

curl --request POST \
  --url http://localhost:8000/api/admin/import/upload/start \
  --header 'Content-Type: application/json' \
  --data '
{
  "total_size": 0,
  "filename": "filename"
}
'

shell

Example Request Body

{
  "total_size": 0,
  "filename": "filename"
}

json

Example Responses

{
  "upload_id": "upload_id",
  "received": 0
}

json

application/json

Upload one chunk of an import archive

PUT

http://localhost:8000

/api/admin/import/upload/{upload_id}/chunk

Append raw bytes at the given offset. Offsets must be contiguous — on mismatch (e.g. a retried chunk that already landed) the response is 409 with the server's current byte count so the client can resync.

Upload one chunk of an import archive › path Parameters

upload_id

string · required

Upload one chunk of an import archive › query Parameters

offset

integer · min: 0 · required

Byte offset this chunk starts at

Upload one chunk of an import archive › Responses

Chunk appended

received

integer

Total bytes received so far

PUT/api/admin/import/upload/{upload_id}/chunk

curl --request PUT \
  --url 'http://localhost:8000/api/admin/import/upload/:upload_id/chunk?offset=%3Cnumber%3E'

shell

Example Responses

{
  "received": 0
}

json

application/json

Finish a chunked upload and start the import

POST

http://localhost:8000

/api/admin/import/upload/{upload_id}/finish

Validates that all declared bytes arrived, then starts the same background import task as /api/admin/import.

Finish a chunked upload and start the import › path Parameters

upload_id

string · required

Finish a chunked upload and start the import › query Parameters

mode

string · enum

Enum values:

clean

replace

Default: clean

Finish a chunked upload and start the import › Responses

Import task started

task_id

string

status

string

message

string

POST/api/admin/import/upload/{upload_id}/finish

curl --request POST \
  --url http://localhost:8000/api/admin/import/upload/:upload_id/finish

shell

Example Responses

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

json

application/json

Abort a chunked import upload

DELETE

http://localhost:8000

/api/admin/import/upload/{upload_id}

Discard the upload session and its partial file. Idempotent.

Abort a chunked import upload › path Parameters

upload_id

string · required

Abort a chunked import upload › Responses

200

Upload aborted

No data returned

DELETE/api/admin/import/upload/{upload_id}

curl --request DELETE \
  --url http://localhost:8000/api/admin/import/upload/:upload_id

shell

Example Responses

No example specified for this content type

Instance status (redeploy safety)

GET

http://localhost:8000

/api/instance/status

Single-call operational snapshot for deploy automation to decide whether this instance can be safely restarted/upgraded. safe_to_redeploy is false while destructible work is in flight — documents being processed/extracted, running background tasks (held in an in-memory store a restart would lose), or an active AskAI/research query (a restart kills the stream). Pending documents persist and resume after a restart, so they are reported but never block. Requires manage permission.

Instance status (redeploy safety) › Responses

Instance status snapshot

safe_to_redeploy

boolean

False while any destructible work is in flight

reasons

string[]

Active blockers; empty when safe to redeploy

processing_count

integer

Documents currently processing/extracting (blocks redeploy)

pending_count

integer

Documents queued (informational; resumes after restart)

failed_count

integer

Documents in failed state

running_task_count

integer

Pending/running background tasks (blocks redeploy)

object[]

Summaries of in-flight background tasks

active_query_count

integer

In-flight AskAI/research queries (blocks redeploy)

last_query_at

string | null · date-time

ISO timestamp of the most recent AskAI query

last_relationship_analysis_at

string | null · date-time

last_community_detection_at

string | null · date-time

last_entity_merge_at

string | null · date-time

neo4j_connected

boolean

checked_at

string · date-time

ISO timestamp when this snapshot was taken

GET/api/instance/status

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

shell

Example Responses

{
  "safe_to_redeploy": true,
  "reasons": [
    "string"
  ],
  "processing_count": 0,
  "pending_count": 0,
  "failed_count": 0,
  "running_task_count": 0,
  "running_tasks": [
    {
      "task_id": "task_id",
      "task_type": "task_type",
      "status": "status",
      "progress_percent": 0,
      "message": "message",
      "started_at": "2024-08-25T15:00:00Z"
    }
  ],
  "active_query_count": 0,
  "last_query_at": "2024-08-25T15:00:00Z",
  "last_relationship_analysis_at": "2024-08-25T15:00:00Z",
  "last_community_detection_at": "2024-08-25T15:00:00Z",
  "last_entity_merge_at": "2024-08-25T15:00:00Z",
  "neo4j_connected": true,
  "checked_at": "2024-08-25T15:00:00Z"
}

json

application/json

List API keys with usage stats

GET

http://localhost:8000

/api/admin/api-keys/with-stats

List all API keys with embedded usage statistics (total/today/week/month requests, error counts, endpoint breakdown). Admin-only.

List API keys with usage stats › Responses

200

API keys with stats retrieved

object[]

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

GET/api/admin/api-keys/with-stats

curl --request GET \
  --url http://localhost:8000/api/admin/api-keys/with-stats

shell

Example Responses

[
  {
    "id": "id",
    "name": "name",
    "key_prefix": "key_prefix",
    "permissions": [
      "read"
    ],
    "is_active": true,
    "created_at": "2024-08-25T15:00:00Z",
    "last_used_at": "2024-08-25T15:00:00Z",
    "created_by": "created_by",
    "collection_scope": "collection_scope",
    "allowed_collections": [
      "string"
    ],
    "allowed_collection_names": {},
    "stats": {
      "total_requests": 0,
      "requests_today": 0,
      "requests_this_week": 0,
      "requests_this_month": 0,
      "error_count": 0,
      "last_error_at": "2024-08-25T15:00:00Z",
      "last_error_message": {},
      "endpoint_breakdown": {}
    }
  }
]

json

application/json

Get API key usage stats

GET

http://localhost:8000

/api/admin/api-keys/{key_id}/stats

Get detailed usage statistics for a specific API key. Admin-only.

Get API key usage stats › path Parameters

key_id

string · required

Get API key usage stats › Responses

Usage statistics retrieved

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

GET/api/admin/api-keys/{key_id}/stats

curl --request GET \
  --url http://localhost:8000/api/admin/api-keys/:key_id/stats

shell

Example Responses

{
  "total_requests": 0,
  "requests_today": 0,
  "requests_this_week": 0,
  "requests_this_month": 0,
  "error_count": 0,
  "last_error_at": "2024-08-25T15:00:00Z",
  "last_error_message": {},
  "endpoint_breakdown": {}
}

json

application/json

Get API key usage history

GET

http://localhost:8000

/api/admin/api-keys/{key_id}/usage-history

Get daily request and error counts for an API key over the given number of days (default 30, max 365). Useful for charting usage trends. Admin-only.

Get API key usage history › path Parameters

key_id

string · required

Get API key usage history › query Parameters

days

integer · min: 1 · max: 365

Number of days of history

Default: 30

Get API key usage history › Responses

Usage history retrieved

key_id

string

key_name

string

object[]

period_days

integer

GET/api/admin/api-keys/{key_id}/usage-history

curl --request GET \
  --url http://localhost:8000/api/admin/api-keys/:key_id/usage-history

shell

Example Responses

{
  "key_id": "key_id",
  "key_name": "key_name",
  "history": [
    {
      "date": "date",
      "requests": 0,
      "errors": 0
    }
  ],
  "period_days": 0
}

json

application/json

Get admin stats overview

GET

http://localhost:8000

/api/admin/stats/overview

Get aggregated statistics across all API keys for the admin dashboard: total/active key counts, request totals over multiple windows, total errors, most active key, and aggregated endpoint breakdown. Admin-only.

Get admin stats overview › Responses

200

Overview retrieved

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

GET/api/admin/stats/overview

curl --request GET \
  --url http://localhost:8000/api/admin/stats/overview

shell

Example Responses

{
  "total_keys": 0,
  "active_keys": 0,
  "total_requests_all_time": 0,
  "total_requests_today": 0,
  "total_requests_this_week": 0,
  "total_requests_this_month": 0,
  "total_errors": 0,
  "most_active_key": {},
  "endpoint_breakdown": {}
}

json

application/json

Tasks Web Import