Skip to main content
POST
/
agents
/
{agent_id}
/
query
/
acl
Query
curl --request POST \
  --url https://api.contextual.ai/v1/agents/{agent_id}/query/acl \
  --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": {
    "json_schema": {},
    "type": "JSON"
  },
  "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",
  "workflow_trace": [
    {
      "duration": 123,
      "name": "<string>",
      "parent_id": "<string>",
      "version": "v0"
    }
  ],
  "dynamic_agent_trace": {},
  "outputs": {},
  "retrieval_contents": [
    {
      "type": "<string>",
      "format": "pdf",
      "content_id": "<string>",
      "doc_id": "<string>",
      "doc_name": "<string>",
      "custom_metadata": {},
      "custom_metadata_config": {},
      "number": 1,
      "datastore_id": "<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
    }
  ],
  "message": {
    "content": "<string>",
    "role": "user",
    "custom_tags": [
      "<string>"
    ]
  },
  "attributions": [
    {
      "start_idx": 123,
      "end_idx": 123,
      "content_ids": [
        "<string>"
      ]
    }
  ],
  "groundedness_scores": [
    {
      "start_idx": 123,
      "end_idx": 123,
      "score": 123
    }
  ],
  "rl_training_context": {}
}

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
Structured Output · object

Custom output structure format.

​
documents_filters
BaseMetadataFilter · object

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.

Example:
{
  "filters": [
    {
      "field": "field1",
      "operator": "equals",
      "value": "value1"
    }
  ],
  "operator": "AND"
}
​
override_configuration
Override Configuration · object

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

Response

Successful Response

Response body for POST /query/acl

​
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.

​
message_id
string<uuid>

A unique identifier for this specific message

​
workflow_trace
ACLWorkflowEvent · object[]

Workflow trace for the response

​
dynamic_agent_trace
Dynamic Agent Trace · object

Tool calls and thinking events for the response

​
outputs
Outputs · object

Outputs of the agent

​
retrieval_contents
RetrievalContentV0_1 · object[]

Relevant content retrieved to answer the query. Only included when include_retrieval_content_text is true.

​
message
Message · object

Response to the query request. Extracted from outputs['response'] if available.

​
attributions
AttributionV0_1 · object[]

Attributions for the response. Extracted from outputs['attribution_result'].attributions if available.

​
groundedness_scores
GroundednessScore · object[]

Groundedness scores for the response. Extracted from outputs['groundedness_scores'] if available.

​
rl_training_context
Rl Training Context · object

RL training context for multi-turn training. Automatically included when policy_output is provided. Contains: full_message_history (complete conversation for next turn), message_history (original input), research_items (tool calls + results), tool_calls_summary (simplified), chunks_info (retrieved content).