> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anagram.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The request

> What Anagram sends to your external knowledge endpoint.

Anagram makes one HTTPS `POST` per question. There is no handshake, no discovery call, and no batching.

## Method and headers

```http theme={null}
POST /your/configured/path HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer <your secret>
```

| Header           | Value                                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`   | Always `application/json`.                                                                                                  |
| `Accept`         | Always `application/json`.                                                                                                  |
| Your auth header | The header name you configured (default `Authorization`) with the saved secret as its value. Omitted if no secret is saved. |

The auth header name must be a valid HTTP token. Anagram refuses names it owns or that would change transport behavior: `Host`, `Content-Length`, `Content-Type`, `Accept`, `Connection`, `Transfer-Encoding`, `TE`, `Trailer`, `Upgrade`, `Keep-Alive`, `Expect`, `Cookie`, and `Set-Cookie`. The value may not contain line breaks or NUL bytes.

Anagram sends no cookies and does not follow redirects. Requests originate from Anagram's servers, not from the shopper's browser, so there is no CORS involved.

## Body

```json theme={null}
{
  "version": 1,
  "question": "Which rod characteristics fit river smallmouth in October using finesse jigs?"
}
```

| Field      | Type   | Notes                                                                                           |
| ---------- | ------ | ----------------------------------------------------------------------------------------------- |
| `version`  | `1`    | Contract version. Always `1` today. Reject anything else so a future version cannot be misread. |
| `question` | string | 1–2,000 characters. Plain text.                                                                 |

Unknown fields will never appear. If you want to be strict, reject bodies with extra keys.

## What the question looks like

The agent writes the question, not the shopper. It folds in the context the shopper has given so far (conditions, use case, experience level, location, constraints) into one self-contained sentence or two. You do not receive the conversation transcript, the shopper's identity, the cart, or the page they are on.

Some real examples of what arrives:

```text theme={null}
Which insulated glove fits a multi-day expedition in Alaska at -30°C where dexterity matters less than warmth?
```

```text theme={null}
Is a GORE-TEX shell overkill for resort skiing in Colorado in February?
```

```text theme={null}
A splitboarder in the Pacific Northwest wants waterproof gloves for wet, stormy touring days. What features matter most?
```

Design your endpoint to answer that kind of question directly. If the question needs more context than it carries, return `no_answer` rather than guessing.

## When and how often

* The agent decides per turn whether your source is relevant. Many turns produce zero requests.
* At most 2 requests are sent per shopper turn. If the agent asks the same question twice in one turn, only one request goes out.
* Requests can arrive concurrently across different shoppers. Plan capacity for your shopper traffic, not for a fixed rate.
* There are no retries. A failed request is a failed turn, not a queued one.

The **Test a question** button in Studio sends exactly this request to your endpoint, so you can watch a live request land in your logs before enabling the source.