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

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agent_id
string<uuid>
required

Agent ID of the agent to query

Query Parameters

​
retrievals_only
boolean
default:false

Set to true to fetch retrieval content and metadata, and then skip generation of the response.

​
include_retrieval_content_text
boolean
default:false

Set to true to include the text of the retrieved contents in the response. If false, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if retrievals_only is true, in which case content_text will always be returned. Content text and other metadata can also be fetched separately using the /agents/{agent_id}/query/{message_id}/retrieval/info endpoint.

Body

application/json

Request body for a POST /agents/{agent_id}/query request

​
messages
MessageAndRole · object[]
required

Messages sent so far in the conversation, ending in the latest user message. Add multiple objects to provide conversation history. Last message in the list must be a user-sent message (i.e. role equals "user").

​
stream
boolean
default:false

Set to true to receive a streamed response

​
conversation_id
string<uuid>

An optional alternative to providing message history in the messages field. If provided, all messages in the messages list prior to the latest user-sent query will be ignored.

​
llm_model_id
string

Model ID of the specific fine-tuned or aligned LLM model to use. Defaults to base model if not specified.

​
structured_output
object

Custom output structure format.

​
documents_filters
object

Defines an Optional custom metadata filter, which can be a list of filters or nested filters. Use lowercase for value and/or field.keyword for field when not using equals operator.The expected input is a nested JSON object that can represent a single filter or a composite (logical) combination of filters.

Unnested Example:

{
        		"operator": "AND",
        		"filters": [
            			{"field": "status", "operator": "equals", "value": "active"},
        		]
    	}

Nested example:

{
        		"operator": "AND",
        		"filters": [
            			{"field": "status", "operator": "equals", "value": "active"},
            			{
                				"operator": "OR",
                				"filters": [
                    					{"field": "category", "operator": "containsany", "value": ["policy", "HR"]},
                    					{"field": "tags", "operator": "exists"}
                				]
            			}
        		]
    	}

Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example:

{"field": "title", "operator": "startswith", "value": "hr-"}

Use lowercase for value when not using equals operator. For document_id and date_created the query is built using direct query without nesting.

  • BaseMetadataFilter
  • CompositeMetadataFilter
Examples:
{
  "filters": [
    {
      "field": "field1",
      "operator": "equals",
      "value": "value1"
    }
  ],
  "operator": "AND"
}
{
  "filters": [
    {
      "field": "field1",
      "operator": "equals",
      "value": "value1"
    },
    {
      "filters": [
        {
          "field": "filed1",
          "operator": "containsany",
          "value": ["value1", "value2"]
        },
        { "field": "field2", "operator": "exists" }
      ],
      "operator": "OR"
    }
  ],
  "operator": "AND"
}
​
override_configuration
object

This will modify select configuration parameters for the agent during the response generation.

Response

Successful Response

Response body for POST /query

​
conversation_id
string<uuid>
required

A unique identifier for the conversation. Can be passed to future /query calls to continue a conversation with the same message history.

​
retrieval_contents
RetrievalContentV0_1 · object[]
required

Relevant content retrieved to answer the query

​
message_id
string<uuid>

A unique identifier for this specific message

​
message
object

Response to the query request

​
attributions
AttributionV0_1 · object[]

Attributions for the response

​
groundedness_scores
GroundednessScore · object[]

Groundedness scores for the response