POST
/
agents
/
{agent_id}
/
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"
    }
  ],
  "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"
  }
}'
{
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": {
    "content": "<string>",
    "role": "user"
  },
  "retrieval_contents": [
    {
      "number": 1,
      "type": "<string>",
      "format": "pdf",
      "content_id": "<string>",
      "doc_id": "<string>",
      "doc_name": "<string>",
      "page": 123,
      "content_text": "<string>",
      "url": "<string>"
    }
  ],
  "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
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
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").

Message object for a message sent or received in a conversation

​
stream
boolean
default:false

Set to true to receive a streamed response

​
conversation_id
string

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. 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"}
                				]
            			}
        		]
    	}
Example:
{
  "filters": [
    {
      "field": "field1",
      "operator": "equals",
      "value": "value1"
    }
  ],
  "operator": "AND"
}

Response

200
application/json
Successful Response

Response body for POST /query

​
conversation_id
string
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
object[]
required

Relevant content retrieved to answer the query

Retrieval content object typing for v0.1 API.

​
message_id
string

A unique identifier for this specific message

​
message
object

Response to the query request

​
attributions
object[]

Attributions for the response

Attribution for some claim made in a generated message`.

​
groundedness_scores
object[]

Groundedness scores for the response

Groundedness scores in a generated message`.

Was this page helpful?