Agent hints

Store a reusable Agent Hints object and reference it by id, or send hints inline on any request. Hints express intent without provider-specific knobs.

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.

You can send hints two ways:

Inline on any request via the Agent-Hints header (base64url-encoded JSON). See 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.

Store a hints object

POST /v2/agent-hints

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

versionstring

The contract version, e.g. 2026-06-01.

reuseobject

Reuse intent: preference (bypass / allow / prefer), scope (project / session / none), retention_preference.

qosobject

QoS targets: class (interactive / standard / background / batch), target_ttft_ms, deadline_ms, priority, degrade_policy (forbid / allow_compatible_fallback).

routingobject

Routing constraints: region_policy, execution_profiles, data_boundary.

stateobject

State placement: bundle_refs, placement_preference.

sessionobject

Session lineage: session_id, branch_id, expected_branch_version.

safetyobject

Retry safety: retry_safety, tool_side_effect_mode.

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" }
  }'

{
  "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" }
}

idstring

Opaque hints id, prefixed ah_. Send it as Agent-Hints-Ref on later requests.

objectstring

Always agent_hints.

project_idstring

The owning project.

created_atstring

RFC 3339 creation timestamp.

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

Retrieve a hints object

GET /v2/agent-hints/{hints_id}

hints_idstringpathrequired

The ah_... id to fetch.

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

Returns the same stored hints object.

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.

Agent hints

Store a hints object

Retrieve a hints object

Errors

On this page