# POST /v1/ask

Source: https://docs.temprl.org/api/ask

> Reference for POST /v1/ask - request body fields, state, questions, media, derive and options, with examples.

Answers every question in `questions` about `state`, in one request.

```text
POST https://api.temprl.org/v1/ask
Authorization: Bearer simo_sk_...
Content-Type: application/json
```

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `state` | string or object | yes | The situation. A string, or a JSON object whose keys become labels. May contain `<image:N>` and `<video:N>` placeholders |
| `questions` | object | yes | `{id: question}`. At least one. See [Question objects](https://docs.temprl.org/api/questions) |
| `model` | string | no | `simo-1-pro` (default) |
| `media` | array | no | Images and videos, in placeholder order. See [Media](#media) |
| `derive` | object | no | `{name: spec}`: exact arithmetic over values read. Turns on `two_pass`. See [derive](#derive) |
| `options` | object | no | See [Options](#options) |

`Example body`

```json
{
  "model": "simo-1-pro",
  "state": {
    "policy": "Refunds are allowed within 30 days of delivery.",
    "ticket": "My order A-1042 arrived 12 days ago, broken. I want my money back."
  },
  "questions": {
    "eligible": {"type": "noul", "instructions": "The customer is eligible for a refund under the policy"},
    "order": {"type": "extract", "instructions": "the order number", "kind": "text", "many": false, "max_tokens": 8}
  },
  "options": {"self_check": 1}
}
```

## Media

Each item matches a placeholder in `state`, in order: the first image is `<image:1>`, the first video `<video:1>`.

| Item | Shape |
|---|---|
| Image | `{"type": "image", "data": "data:image/png;base64,..."}` |
| Video | `{"type": "video", "frames": ["data:image/png;base64,...", ...], "fps": 1.0}` |

`fps` is the rate the frames were sampled at; it sets the timestamps the model sees. A request holds at most 16 pictures, video frames included, and the whole body at most 25 MB. Placeholders that don't match `media` (wrong order, missing or extra) are rejected.

## derive

```json
"derive": {
  "days":  {"op": "days_between", "from": "accident", "to": "filed", "instructions": "days from accident to claim"},
  "delta": {"op": "difference", "from": "quoted", "to": "billed"},
  "total": {"op": "sum", "of": ["item_1", "item_2", "item_3"]}
}
```

Inputs are ids of `fill` or `extract` questions in the same request. A derived name must not be a question id. Each derived value comes back in `answers` as a fill answer. See [Read first, then decide](https://docs.temprl.org/guide/read-then-decide).

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `self_check` | 0 or 1 | service default | Add `check`, a calibrated P(the value is right), to every fill and extract answer |
| `debias` | integer | 1 | Read each choice under this many option orders and average |
| `two_pass` | 0 or 1 | 0 | Answer reads first, then decisions with the values read written in |
| `cache` | 0 or 1 | 1 | 0 bypasses the exact-request response cache |

## Headers

| Request header | Description |
|---|---|
| `Authorization` | `Bearer simo_sk_...` (required) |
| `Content-Type` | `application/json` (required) |

## Response

`200 OK` with the answers. See [Response format](https://docs.temprl.org/api/response).

```json
{
  "id": "evt_...",
  "model": "simo-1-pro",
  "answers": {
    "eligible": {"type": "noul", "noul": 0.982},
    "order": {"type": "extract", "value": "A-1042", "valid": true, "confidence": 0.99, "check": 0.98}
  },
  "usage": {"input_tokens": 68, "output_tokens": 0, "cost": 0.00000204}
}
```

Errors: see [Errors](https://docs.temprl.org/api/errors).