Skip to main content
POST
/
agents
/
{agent_id}
/
query
Query
curl --request POST \
  --url https://api.contextual.ai/v1/agents/{agent_id}/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {
      "content": "<string>",
      "role": "user",
      "custom_tags": [
        "<string>"
      ]
    }
  ],
  "stream": false,
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "llm_model_id": "<string>",
  "structured_output": {
    "type": "JSON",
    "json_schema": {}
  },
  "documents_filters": {
    "filters": [
      {
        "field": "field1",
        "operator": "equals",
        "value": "value1"
      }
    ],
    "operator": "AND"
  },
  "override_configuration": {
    "system_prompt": "<string>",
    "filter_prompt": "<string>",
    "model": "<string>",
    "max_new_tokens": 123,
    "top_p": 123,
    "temperature": 123,
    "top_k_retrieved_chunks": 123,
    "top_k_reranked_chunks": 123,
    "enable_filter": true,
    "filter_model": "<string>",
    "enable_rerank": true,
    "reranker": "<string>",
    "lexical_alpha": 123,
    "semantic_alpha": 123,
    "rerank_instructions": "<string>",
    "reranker_score_filter_threshold": 123
  }
}'
{
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": {
    "content": "<string>",
    "role": "user",
    "custom_tags": [
      "<string>"
    ]
  },
  "retrieval_contents": [
    {
      "custom_metadata": {},
      "custom_metadata_config": {},
      "number": 1,
      "type": "<string>",
      "format": "pdf",
      "content_id": "<string>",
      "datastore_id": "<string>",
      "doc_id": "<string>",
      "doc_name": "<string>",
      "page": 123,
      "content_text": "<string>",
      "url": "<string>",
      "ctxl_metadata": {
        "document_title": "<string>",
        "section_title": "<string>",
        "is_figure": true,
        "file_name": "<string>",
        "chunk_size": 123,
        "file_format": "<string>",
        "page": 123,
        "chunk_id": "<string>",
        "date_created": "<string>",
        "section_id": "<string>"
      },
      "score": 123
    }
  ],
  "attributions": [
    {
      "start_idx": 123,
      "end_idx": 123,
      "content_ids": [
        "<string>"
      ]
    }
  ],
  "groundedness_scores": [
    {
      "start_idx": 123,
      "end_idx": 123,
      "score": 123
    }
  ]
}

Authorizations

Authorization
string
header
required

Path Parameters

agent_id
string<uuid>
required

Query Parameters

retrievals_only
boolean
default:false
include_retrieval_content_text
boolean
default:false

Body

application/json
messages
MessageAndRole · object[]
required
stream
boolean
default:false
conversation_id
string<uuid>
llm_model_id
string
structured_output
object
documents_filters
object
  • BaseMetadataFilter
  • CompositeMetadataFilter
Examples:
override_configuration
object

Response

conversation_id
string<uuid>
required
retrieval_contents
RetrievalContentV0_1 · object[]
required
message_id
string<uuid>
message
object
attributions
AttributionV0_1 · object[]
groundedness_scores
GroundednessScore · object[]