> ## Documentation Index > Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt > Use this file to discover all available pages before exploring further. # Query > Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions. ## OpenAPI ````yaml api-reference/openapi.json post /agents/{agent_id}/query/acl openapi: 3.1.0 info: title: Endpoints version: '1.0' servers: - url: https://api.contextual.ai/v1 security: - BearerAuth: [] paths: /agents/{agent_id}/query/acl: post: tags: - /agents/{id}/query summary: Query description: >- Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions. operationId: Query_agents__agent_id__query_acl_post parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: Agent ID of the agent to query title: Agent Id description: Agent ID of the agent to query - name: retrievals_only in: query required: false schema: type: boolean description: >- Set to `true` to fetch retrieval content and metadata, and then skip generation of the response. default: false title: Retrievals Only description: >- Set to `true` to fetch retrieval content and metadata, and then skip generation of the response. - name: include_retrieval_content_text in: query required: false schema: type: boolean description: >- 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. default: false title: Include Retrieval Content Text description: >- 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryRequestV1' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ACLQueryResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: QueryRequestV1: properties: messages: items: $ref: '#/components/schemas/MessageAndRole' type: array title: Messages description: >- 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: type: boolean title: Stream description: Set to `true` to receive a streamed response default: false conversation_id: type: string format: uuid title: Conversation Id description: >- 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: type: string title: Llm Model Id description: >- Model ID of the specific fine-tuned or aligned LLM model to use. Defaults to base model if not specified. structured_output: $ref: '#/components/schemas/StructuredOutput' title: Structured Output description: Custom output structure format. documents_filters: anyOf: - $ref: '#/components/schemas/BaseMetadataFilter' - $ref: '#/components/schemas/CompositeMetadataFilter' title: Documents Filters description: "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.\n\n Unnested Example:\n\n```json\n \t{\n \t\t\"operator\": \"AND\",\n \t\t\"filters\": [\n \t\t\t{\"field\": \"status\", \"operator\": \"equals\", \"value\": \"active\"},\n \t\t]\n \t}\n\n```\n\nNested example:\n\n```json\n \t{\n \t\t\"operator\": \"AND\",\n \t\t\"filters\": [\n \t\t\t{\"field\": \"status\", \"operator\": \"equals\", \"value\": \"active\"},\n \t\t\t{\n \t\t\t\t\"operator\": \"OR\",\n \t\t\t\t\"filters\": [\n \t\t\t\t\t{\"field\": \"category\", \"operator\": \"containsany\", \"value\": [\"policy\", \"HR\"]},\n \t\t\t\t\t{\"field\": \"tags\", \"operator\": \"exists\"}\n \t\t\t\t]\n \t\t\t}\n \t\t]\n \t}\n\n```" 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: $ref: '#/components/schemas/AgentEvaluationConfigOverride' title: Override Configuration description: >- This will modify select configuration parameters for the agent during the response generation. additionalProperties: false type: object required: - messages title: QueryRequestV1 description: Request body for a POST `/agents/{agent_id}/query` request ACLQueryResponse: properties: conversation_id: type: string format: uuid title: Conversation Id description: >- A unique identifier for the conversation. Can be passed to future `/query` calls to continue a conversation with the same message history. message_id: type: string format: uuid title: Message Id description: A unique identifier for this specific message workflow_trace: items: $ref: '#/components/schemas/ACLWorkflowEvent' type: array title: Workflow Trace description: Workflow trace for the response dynamic_agent_trace: additionalProperties: items: $ref: '#/components/schemas/DynamicAgentEvent' type: array type: object title: Dynamic Agent Trace description: Tool calls and thinking events for the response outputs: additionalProperties: true type: object title: Outputs description: Outputs of the agent retrieval_contents: items: $ref: '#/components/schemas/RetrievalContentV0_1' type: array title: Retrieval Contents description: >- Relevant content retrieved to answer the query. Only included when include_retrieval_content_text is true. message: $ref: '#/components/schemas/MessageAndRole' title: Message description: >- Response to the query request. Extracted from outputs['response'] if available. attributions: items: $ref: '#/components/schemas/AttributionV0_1' type: array title: Attributions description: >- Attributions for the response. Extracted from outputs['attribution_result'].attributions if available. groundedness_scores: items: $ref: '#/components/schemas/GroundednessScore' type: array title: Groundedness Scores description: >- Groundedness scores for the response. Extracted from outputs['groundedness_scores'] if available. rl_training_context: additionalProperties: true type: object title: Rl Training Context description: >- 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). type: object required: - conversation_id title: ACLQueryResponse description: Response body for POST /query to Agent Composer HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError MessageAndRole: properties: content: type: string title: Content description: Content of the message role: $ref: '#/components/schemas/SenderType' description: Role of the sender custom_tags: items: type: string type: array title: Custom Tags description: Custom tags for the message type: object required: - content - role title: MessageAndRole description: Message object for a message sent or received in a conversation StructuredOutput: properties: type: $ref: '#/components/schemas/StructuredOutputType' description: Type of the structured output. The default is JSON default: JSON json_schema: additionalProperties: true type: object title: Json Schema description: The output json structure. additionalProperties: false type: object required: - json_schema title: StructuredOutput BaseMetadataFilter: properties: field: type: string title: Field description: Field name to search for in the metadata operator: $ref: '#/components/schemas/FilterMetadataOperator' description: Operator to be used for the filter. value: anyOf: - type: string - type: integer - type: number - type: boolean - items: anyOf: - type: string - type: integer - type: number - type: boolean type: array - type: 'null' title: Value description: >- The value to be searched for in the field. In case of exists operator, it is not needed. type: object required: - field - operator title: BaseMetadataFilter description: >- 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. CompositeMetadataFilter: properties: filters: items: anyOf: - $ref: '#/components/schemas/BaseMetadataFilter' - $ref: '#/components/schemas/CompositeMetadataFilter' type: array title: Filters description: 'Filters added to the query for filtering docs ' operator: anyOf: - $ref: '#/components/schemas/CompositeOperator' - type: 'null' description: Composite operator to be used to combine filters type: object required: - filters title: CompositeMetadataFilter description: >- "Defines a custom metadata filter as a Composite MetadataFilter. Which can be be a list of filters or nested filters. AgentEvaluationConfigOverride: properties: system_prompt: type: string title: System Prompt description: Override the system prompt for the agent during evaluation. filter_prompt: type: string title: Filter Prompt description: Override the filter prompt for the agent during evaluation. model: type: string title: Model description: Override the model for the agent during evaluation. max_new_tokens: type: integer title: Max New Tokens description: Override the max new tokens for the agent during evaluation. top_p: type: number title: Top P description: >- Override the top_p for the query. This will override the top_p for the agent during evaluation. temperature: type: number title: Temperature description: >- Override the temperature for the query. This will override the temperature for the agent during evaluation. top_k_retrieved_chunks: type: integer title: Top K Retrieved Chunks description: >- Override the top_k for the query. This will override the top_k for the agent during evaluation. top_k_reranked_chunks: type: integer title: Top K Reranked Chunks description: >- Override the rerank_top_k for the query. This will override the rerank_top_k for the agent during evaluation. enable_filter: type: boolean title: Enable Filter description: >- Override the filter_retrievals for the query. This will override the filter_retrievals for the agent during evaluation. filter_model: type: string title: Filter Model description: >- Override the filter_model for the query. This will override the filter_model for the agent during evaluation. enable_rerank: type: boolean title: Enable Rerank description: Override the rerank_retrievals for the agent during evaluation. reranker: type: string title: Reranker description: Override the reranker for the agent during evaluation. lexical_alpha: type: number title: Lexical Alpha description: Override the lexical_alpha for the agent during evaluation. semantic_alpha: type: number title: Semantic Alpha description: Override the semantic_alpha for the agent during evaluation. rerank_instructions: type: string title: Rerank Instructions description: Override the rerank_instructions for the agent during evaluation. reranker_score_filter_threshold: type: number title: Reranker Score Filter Threshold description: >- Override the reranker_score_filter_threshold for the agent during evaluation. use_optimized_context: type: boolean title: Use Optimized Context description: >- Override whether to use optimized context for this request. When true, optimized context will be used if available. When false, optimized context is disabled. When null/omitted, uses the agent's configured setting. additionalProperties: false type: object title: AgentEvaluationConfigOverride ACLWorkflowEvent: properties: version: type: string const: v0 title: Version default: v0 duration: type: number title: Duration description: Duration of the workflow event name: type: string title: Name description: Name of the workflow event parent_id: anyOf: - type: string - type: 'null' title: Parent Id description: ID of the parent node in the workflow type: object required: - duration - name - parent_id title: ACLWorkflowEvent DynamicAgentEvent: properties: version: type: string const: v0 title: Version default: v0 event: oneOf: - $ref: '#/components/schemas/ToolCall' - $ref: '#/components/schemas/ThinkingEvent' title: Event discriminator: propertyName: type mapping: thinking_event: $ref: '#/components/schemas/ThinkingEvent' tool_call: $ref: '#/components/schemas/ToolCall' type: object required: - event title: DynamicAgentEvent RetrievalContentV0_1: properties: custom_metadata: additionalProperties: anyOf: - type: boolean - type: number - type: integer - type: string - items: type: number type: array type: object title: Custom Metadata description: >- Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed. custom_metadata_config: additionalProperties: $ref: '#/components/schemas/MetadataFieldConfig' type: object title: Custom Metadata Config description: >- A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits: - Maximum characters per metadata field (for prompt or rerank): **400** - Maximum number of metadata fields (for prompt or retrieval): **10** Contact support@contextual.ai to request quota increases. number: type: integer title: Number description: >- Index of the retrieved item in the retrieval_contents list (starting from 1) default: 1 type: type: string title: Source description: >- Source type of the content. Will be `file` for any docs ingested through ingestion API. format: type: string enum: - pdf - html - htm - mhtml - doc - docx - ppt - pptx title: Format description: Format of the content, such as `pdf` or `html` content_id: type: string title: Content Id description: Unique identifier of the retrieved content datastore_id: type: string title: Datastore Id description: Unique identifier of the datastore doc_id: type: string title: Doc Id description: Unique identifier of the document doc_name: type: string title: Doc Name description: Name of the document page: type: integer title: Page description: Page number of the content in the document content_text: type: string title: Content Text description: >- Text of the retrieved content. Included in response to a query if `include_retrieval_content_text` is True url: type: string title: Url description: URL of the source content, if applicable ctxl_metadata: $ref: '#/components/schemas/InnerRetrievableCtxlMetadata' title: Ctxl Metadata description: Default metadata from the retrieval score: type: number title: Score description: Score of the retrieval, if applicable type: object required: - type - format - content_id - doc_id - doc_name title: RetrievalContentV0_1 description: Retrieval content object typing for v0.1 API. AttributionV0_1: properties: start_idx: type: integer title: Start Idx description: Start index of the attributed text in the generated message end_idx: type: integer title: End Idx description: End index of the attributed text in the generated message content_ids: items: type: string type: array title: Content Ids description: Content IDs of the sources for the attributed text type: object required: - start_idx - end_idx - content_ids title: AttributionV0_1 description: Attribution for some claim made in a generated message`. GroundednessScore: properties: start_idx: type: integer title: Start Index description: Start index of the span in the generated message end_idx: type: integer title: End Index description: End index of the span in the generated message score: type: integer title: Score description: Groundedness score for the span type: object required: - start_idx - end_idx - score title: GroundednessScore description: Groundedness scores in a generated message`. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError SenderType: type: string enum: - user - system - assistant - knowledge title: SenderType StructuredOutputType: type: string enum: - JSON title: StructuredOutputType description: This captures type of the structured data. FilterMetadataOperator: type: string enum: - equals - containsany - exists - startswith - gt - gte - lt - lte - notequals - between - wildcard title: FilterMetadataOperator CompositeOperator: type: string enum: - AND - OR - AND_NOT title: CompositeOperator ToolCall: properties: type: type: string const: tool_call title: Type default: tool_call tool_name: type: string title: Tool Name description: Name of the tool called tool_args: type: string title: Tool Args description: Arguments of the tool called tool_output: type: string title: Tool Output description: Output of the tool called successful: type: boolean title: Successful description: Whether the tool call was successful error: type: string title: Error description: Error message if the tool call was not successful duration: type: number title: Duration description: Duration of the tool call type: object required: - tool_name - tool_args - successful - duration title: ToolCall description: Tool call for the response ThinkingEvent: properties: type: type: string const: thinking_event title: Type default: thinking_event thinking_summary: anyOf: - type: string - type: 'null' title: Thinking Summary description: Thinking summary duration: type: number title: Duration description: Duration of the thinking type: object required: - thinking_summary - duration title: ThinkingEvent description: Thinking event for dynamic agents MetadataFieldConfig: properties: in_chunks: type: boolean title: In Chunks description: >- Whether to add in chunks. Defaults to True. The maximum amount of characters per metadata field that can be added to the prompt or rerank is 400. The maximum amount of metadata fields that can be added for prompt or retrieval is 10. Contact support@contextual.ai to request quota increases. default: true returned_in_response: type: boolean title: Returned In Response description: Whether to add in response. Defaults to False default: false filterable: type: boolean title: Filterable description: Whether to use in filtering. Defaults to True default: true type: object title: MetadataFieldConfig InnerRetrievableCtxlMetadata: properties: document_title: type: string title: Document Title description: Title of the document. section_title: type: string title: Section Title description: Title of the section. is_figure: type: boolean title: Is Figure description: Whether this chunk represents a figure. file_name: type: string title: File Name description: Name of the source file. chunk_size: type: integer title: Chunk Size description: Size of the chunk in tokens or characters. file_format: type: string title: File Format description: Format of the file (e.g., PDF, DOCX). page: type: integer title: Page description: Page number in the source document. chunk_id: type: string title: Chunk Id description: Unique identifier for the chunk. date_created: type: string title: Date Created description: Date when the document or chunk was created. section_id: type: string title: Section Id description: The HTML id of the nearest element of the chunk additionalProperties: true type: object title: InnerRetrievableCtxlMetadata securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````