# Agent hints (/api-v2/agent-hints)



Agent Hints express intent (preferred reuse, QoS targets, routing constraints, retry safety) without exposing any provider- or engine-specific knob. They are not guarantees: an adapter honors what it can, and the platform reports what it honored. Every field is optional and unknown fields are ignored, so a newer client can send richer hints to an older backend safely. Stored hints are prefixed `ah_`. See [agent hints](/concepts/agent-hints).

You can send hints two ways:

* **Inline** on any request via the `Agent-Hints` header (base64url-encoded JSON). See [headers](/api-reference/headers).
* **By reference** via the `Agent-Hints-Ref: ah_...` header, after storing a hints object here.

All requests require a bearer API key. See [authentication](/api-reference/authentication).

## Store a hints object [#store-a-hints-object]

`POST /v2/agent-hints`

The body is an Agent Hints object. Every section is optional.

<ParamField body="version" type="string">
  The contract version, e.g. `2026-06-01`.
</ParamField>

<ParamField body="reuse" type="object">
  Reuse intent: `preference` (`bypass` / `allow` / `prefer`), `scope` (`project` / `session` / `none`), `retention_preference`.
</ParamField>

<ParamField body="qos" type="object">
  QoS targets: `class` (`interactive` / `standard` / `background` / `batch`), `target_ttft_ms`, `deadline_ms`, `priority`, `degrade_policy` (`forbid` / `allow_compatible_fallback`).
</ParamField>

<ParamField body="routing" type="object">
  Routing constraints: `region_policy`, `execution_profiles`, `data_boundary`.
</ParamField>

<ParamField body="state" type="object">
  State placement: `bundle_refs`, `placement_preference`.
</ParamField>

<ParamField body="session" type="object">
  Session lineage: `session_id`, `branch_id`, `expected_branch_version`.
</ParamField>

<ParamField body="safety" type="object">
  Retry safety: `retry_safety`, `tool_side_effect_mode`.
</ParamField>

```bash
curl https://api.zumik.ai/v2/agent-hints \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "2026-06-01",
    "reuse": { "preference": "prefer", "scope": "project" },
    "qos": { "class": "interactive", "target_ttft_ms": 500, "deadline_ms": 5000, "degrade_policy": "allow_compatible_fallback" }
  }'
```

```json
{
  "id": "ah_01jy7nij34n6o7p8q9r0s1t2uv",
  "object": "agent_hints",
  "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
  "created_at": "2026-06-15T16:24:01Z",
  "version": "2026-06-01",
  "reuse": { "preference": "prefer", "scope": "project" },
  "qos": { "class": "interactive", "target_ttft_ms": 500, "deadline_ms": 5000, "degrade_policy": "allow_compatible_fallback" }
}
```

<ResponseField name="id" type="string">
  Opaque hints id, prefixed `ah_`. Send it as `Agent-Hints-Ref` on later requests.
</ResponseField>

<ResponseField name="object" type="string">
  Always `agent_hints`.
</ResponseField>

<ResponseField name="project_id" type="string">
  The owning project.
</ResponseField>

<ResponseField name="created_at" type="string">
  RFC 3339 creation timestamp.
</ResponseField>

The stored hint sections are flattened onto the object alongside `id`, `object`, `project_id`, and `created_at`.

## Retrieve a hints object [#retrieve-a-hints-object]

`GET /v2/agent-hints/{hints_id}`

<ParamField path="hints_id" type="string">
  The `ah_...` id to fetch.
</ParamField>

```bash
curl https://api.zumik.ai/v2/agent-hints/ah_01jy7nij34n6o7p8q9r0s1t2uv \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

Returns the same stored hints object.

## Errors [#errors]

| Status | Code                    | When                                             |
| ------ | ----------------------- | ------------------------------------------------ |
| 401    | `invalid_api_key`       | Missing or invalid API key.                      |
| 404    | `invalid_request_error` | The hints object does not exist in this project. |

See the full table on [errors](/api-reference/errors).