Cortex API

Ask AI

Endpoint

AI-powered question answering

Ask a question (non-streaming, fast chat only)

POST

http://localhost:8000

/api/ask

Get a single-shot AI-generated answer with sources. To retrieve knowledge from the Cortex, prefer a streaming Deep Research query on POST /api/ask/stream with use_agentic: true — use this endpoint only for quick chat answers from callers that cannot consume SSE. Constraints: use_agentic: true is rejected here with 400 {"error": "agentic_requires_streaming"} (agentic runs routinely take 60–90s), and the request is bounded by a server-side deadline (ASK_DEADLINE_SECONDS, default 28s) returning 504 {"error": "deadline_exceeded"} on expiry.

Ask a question (non-streaming, fast chat only) › Request Body

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Deep Research mode (agentic multi-step retrieval). Only honored on the streaming endpoints — the non-streaming POST /api/ask rejects use_agentic: true with 400 agentic_requires_streaming.

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

Ask a question (non-streaming, fast chat only) › Responses

Answer generated

answer

string

object[]

object

retrieval_stats

object

collection_id

string | null

The collection scope actually applied (request or key restriction)

structured

object | null

Parsed JSON answer when response_format was set and parsing succeeded

finish_reason

string | null

Provider finish reason of the answer (stop, length, ...)

truncated

boolean

The answer hit the output-token cap (finish_reason == "length") and is cut short

Default: false

refused

boolean

The answer is the prompt-injection safe refusal, not knowledge — rephrase as a plain question

Default: false

POST/api/ask

curl --request POST \
  --url http://localhost:8000/api/ask \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}
'

shell

Example Request Body

{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}

json

Example Responses

{
  "answer": "answer",
  "sources": [
    {
      "content": "content",
      "document_id": "document_id",
      "filename": "filename",
      "score": 0
    }
  ],
  "graph_context": {
    "entities": [
      "string"
    ],
    "relationships": [
      {}
    ],
    "communities": [
      {}
    ]
  },
  "retrieval_stats": {},
  "collection_id": {},
  "structured": {},
  "finish_reason": {},
  "truncated": true,
  "refused": true
}

json

application/json

Streaming answer (primary retrieval endpoint)

POST

http://localhost:8000

/api/ask/stream

Get a streaming answer using Server-Sent Events. This is the recommended way to ask the Cortex anything: send use_agentic: true for Deep Research (agentic multi-step retrieval with visible reasoning), or omit it for streamed chat. SSE heartbeats keep long runs alive — this endpoint has no server-side deadline.

Streaming answer (primary retrieval endpoint) › Request Body

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Deep Research mode (agentic multi-step retrieval). Only honored on the streaming endpoints — the non-streaming POST /api/ask rejects use_agentic: true with 400 agentic_requires_streaming.

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

Streaming answer (primary retrieval endpoint) › Responses

200

Streaming response

string

POST/api/ask/stream

curl --request POST \
  --url http://localhost:8000/api/ask/stream \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}
'

shell

Example Request Body

{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}

json

Example Responses

string

plain

text/event-stream

Streaming with extended thinking

POST

http://localhost:8000

/api/ask/stream/thinking

Stream answer with visible reasoning steps

Streaming with extended thinking › Request Body

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Deep Research mode (agentic multi-step retrieval). Only honored on the streaming endpoints — the non-streaming POST /api/ask rejects use_agentic: true with 400 agentic_requires_streaming.

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

Streaming with extended thinking › Responses

200

Streaming response with thinking

string

POST/api/ask/stream/thinking

curl --request POST \
  --url http://localhost:8000/api/ask/stream/thinking \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}
'

shell

Example Request Body

{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}

json

Example Responses

string

plain

text/event-stream

Search Knowledge Graph

Cortex API

Ask AI

Endpoint

AI-powered question answering

Ask a question (non-streaming, fast chat only)

POST

http://localhost:8000

/api/ask

Ask a question (non-streaming, fast chat only) › Request Body

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Deep Research mode (agentic multi-step retrieval). Only honored on the streaming endpoints — the non-streaming POST /api/ask rejects use_agentic: true with 400 agentic_requires_streaming.

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

Ask a question (non-streaming, fast chat only) › Responses

Answer generated

answer

string

object[]

object

retrieval_stats

object

collection_id

string | null

The collection scope actually applied (request or key restriction)

structured

object | null

Parsed JSON answer when response_format was set and parsing succeeded

finish_reason

string | null

Provider finish reason of the answer (stop, length, ...)

truncated

boolean

The answer hit the output-token cap (finish_reason == "length") and is cut short

Default: false

refused

boolean

The answer is the prompt-injection safe refusal, not knowledge — rephrase as a plain question

Default: false

POST/api/ask

curl --request POST \
  --url http://localhost:8000/api/ask \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}
'

shell

Example Request Body

{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}

json

Example Responses

{
  "answer": "answer",
  "sources": [
    {
      "content": "content",
      "document_id": "document_id",
      "filename": "filename",
      "score": 0
    }
  ],
  "graph_context": {
    "entities": [
      "string"
    ],
    "relationships": [
      {}
    ],
    "communities": [
      {}
    ]
  },
  "retrieval_stats": {},
  "collection_id": {},
  "structured": {},
  "finish_reason": {},
  "truncated": true,
  "refused": true
}

json

application/json

Streaming answer (primary retrieval endpoint)

POST

http://localhost:8000

/api/ask/stream

Streaming answer (primary retrieval endpoint) › Request Body

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Deep Research mode (agentic multi-step retrieval). Only honored on the streaming endpoints — the non-streaming POST /api/ask rejects use_agentic: true with 400 agentic_requires_streaming.

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

Streaming answer (primary retrieval endpoint) › Responses

200

Streaming response

string

POST/api/ask/stream

curl --request POST \
  --url http://localhost:8000/api/ask/stream \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}
'

shell

Example Request Body

{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}

json

Example Responses

string

plain

text/event-stream

Streaming with extended thinking

POST

http://localhost:8000

/api/ask/stream/thinking

Stream answer with visible reasoning steps

Streaming with extended thinking › Request Body

question

string · required

use_graph

boolean

Default: true

max_hops

integer

Default: 2

use_reranking

boolean

Default: true

use_agentic

boolean

Deep Research mode (agentic multi-step retrieval). Only honored on the streaming endpoints — the non-streaming POST /api/ask rejects use_agentic: true with 400 agentic_requires_streaming.

Default: false

use_fast_search

boolean

Default: false

collection_id

string

object[]

Streaming with extended thinking › Responses

200

Streaming response with thinking

string

POST/api/ask/stream/thinking

curl --request POST \
  --url http://localhost:8000/api/ask/stream/thinking \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}
'

shell

Example Request Body

{
  "question": "question",
  "use_graph": true,
  "max_hops": 0,
  "use_reranking": true,
  "use_agentic": true,
  "use_fast_search": true,
  "collection_id": "collection_id",
  "conversation_history": [
    {
      "role": "user",
      "content": "content"
    }
  ]
}

json

Example Responses

string

plain

text/event-stream

Search Knowledge Graph