# Qualcomm AI Agent Query API (ACL)

This reference describes the agent query endpoint exposed through the gateway. The agent ID, workspace, gateway host, and bearer token are deployment-specific values.

## Endpoint

```http
POST https://dev.apigwx-op.qualcomm.com/ce/v1/contextual-ai-harness/agents/{agent_id}/query/acl
```

Replace `{agent_id}` with the UUID of the agent to query.

## Authentication and headers

Every request requires a production-issued bearer token and the workspace header.

| Header | Required | Description |
| --- | --- | --- |
| `Authorization` | Yes | `Bearer <production-issued-token>` |
| `Contextual-Workspace` | Yes | Workspace containing the agent, such as `dragon` |
| `Content-Type` | Yes | `application/json` |
| `Accept` | Recommended | `application/json` |

## Basic request

The smallest useful request sends one user message and disables upstream streaming:

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "stream": false
}
```

The gateway returns the API's JSON response, including the generated agent message and any available retrieval or attribution data.

## Portal credentials

The token portal may provide two credentials for local tooling:

```bash
export QUALCOMM_AI_API_TOKEN='<access-token>'
export QUALCOMM_AI_REFRESH_TOKEN='<refresh-token>'
```

Use the access token as the bearer token in API requests. The refresh token is only for an OAuth-aware client that needs to obtain a new access token after expiry. Never send the refresh token to the Query/ACL endpoint, place it in the `Authorization` header, or commit it to source control.

The MCP server uses `QUALCOMM_AI_API_TOKEN` for requests and `QUALCOMM_AI_REFRESH_TOKEN` with the portal refresh endpoint when renewal is needed. The refresh token is not itself an API request credential.

For MCP clients, configure the portal refresh endpoint as `QUALCOMM_AI_TOKEN_REFRESH_URL`. A successful refresh returns a new access token and may return a rotated refresh token. The MCP server stores rotated refresh tokens in the operating system credential store when available.

The portal refresh broker accepts the refresh token only for OAuth renewal:

```http
POST /api/mcp/refresh
Content-Type: application/json

{"refresh_token":"<refresh-token>"}
```

The broker returns a new access token and expiry metadata. It does not forward the refresh token to the Query/ACL API.

## URL query parameters

These options belong in the URL query string, not in the JSON request body.

| Parameter | Default | Description |
| --- | --- | --- |
| `retrievals_only` | `false` | Return retrieved sources without generating an answer. |
| `include_retrieval_content_text` | `false` | Include retrieved source text with the answer. Retrieval-only requests include source text automatically. |

Example:

```text
...?retrievals_only=false&include_retrieval_content_text=true
```

## Request body

### Messages

`messages` is an array of conversation turns. The latest user message should be appended as the final item.

| Field | Type | Description |
| --- | --- | --- |
| `role` | string | One of `user`, `assistant`, `system`, or `knowledge`. |
| `content` | string | Message text. |
| `custom_tags` | string array | Optional tags associated with a message. |

### Conversation state

Use either `conversation_id` or earlier messages in `messages`:

| Field | Type | Description |
| --- | --- | --- |
| `conversation_id` | UUID | Continue a conversation using the ID returned by an earlier query to the same agent. |
| `messages` | array | Supply earlier turns in chronological order, followed by the latest user message. |

Do not combine `conversation_id` with a non-empty message history. When a conversation ID is supplied, earlier messages may be ignored by the upstream API.

### Optional body fields

| Field | Type | Description |
| --- | --- | --- |
| `llm_model_id` | string | Fine-tuned or aligned model ID available to the selected agent. |
| `structured_output` | object | Request an answer matching a JSON Schema. Use `type: "JSON"` and provide `json_schema`. |
| `documents_filters` | object | Filter document metadata, including nested logical groups. |
| `override_configuration` | object | Override generation, retrieval, filtering, reranking, and prompt settings for this request only. |

### Document filters

A simple document filter has a field, operator, and comparison value:

```json
{
  "documents_filters": {
    "field": "department",
    "operator": "equals",
    "value": "finance"
  }
}
```

Nested filters use `AND`, `OR`, or `AND_NOT`:

```json
{
  "documents_filters": {
    "operator": "AND",
    "filters": [
      {
        "field": "department",
        "operator": "equals",
        "value": "finance"
      },
      {
        "field": "confidential",
        "operator": "equals",
        "value": false
      }
    ]
  }
}
```

Supported comparison operators include `equals`, `containsany`, `exists`, `startswith`, `gt`, `gte`, `lt`, `lte`, `notequals`, `between`, and `wildcard`.

### Structured output

```json
{
  "structured_output": {
    "type": "JSON",
    "json_schema": {
      "type": "object",
      "properties": {
        "answer": { "type": "string" }
      },
      "required": ["answer"]
    }
  }
}
```

### Override configuration

`override_configuration` changes settings for one request and does not permanently modify the agent.

| Category | Fields |
| --- | --- |
| Generation | `system_prompt`, `model`, `max_new_tokens`, `top_p`, `temperature` |
| Retrieval | `top_k_retrieved_chunks`, `lexical_alpha`, `semantic_alpha`, `use_optimized_context` |
| Filtering | `enable_filter`, `filter_prompt`, `filter_model` |
| Reranking | `enable_rerank`, `reranker`, `top_k_reranked_chunks`, `rerank_instructions`, `reranker_score_filter_threshold` |

## Complete request example

```bash
curl --request POST \
  --url 'https://dev.apigwx-op.qualcomm.com/ce/v1/contextual-ai-harness/agents/d6c12230-018a-4b99-af1b-e0bed13dd49a/query/acl?include_retrieval_content_text=true' \
  --header 'Authorization: Bearer <production-issued-token>' \
  --header 'Contextual-Workspace: dragon' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "messages": [
      {"role": "user", "content": "What does the onboarding policy say about account access?"}
    ],
    "stream": false
  }'
```

## Follow-up request

Use the `conversation_id` returned by the previous response to continue the same conversation:

```json
{
  "conversation_id": "00000000-0000-4000-8000-000000000001",
  "messages": [
    {
      "role": "user",
      "content": "Which exceptions does that policy allow?"
    }
  ],
  "stream": false
}
```

## Operational notes

- Keep bearer tokens out of source control, client-side code, and checked-in configuration files.
- The agent, workspace, and token must be authorized for one another.
- Set `stream` to `false` when the caller expects one JSON response.
- If an optional setting is rejected, retry with the basic `messages` and `stream` fields to determine which options are enabled for the deployed agent.