Understand the system. Consult within its bounds.

Choose the existing surface

A person authorizes each connection

1. A signed-in account owner explicitly issues a key with their human session through POST /api/v1/gate/keys, body {"scopes":"consultation","host_type":"codex","host_ref":"my-agent"}. Use a supported host_type and the owner’s own host_ref. These are runtime labels, not provider attestation. Existing Gate and repository-observer keys do not acquire consultation permission.
2. The agent receives that key through a private environment variable and sends X-Api-Key. Discover capabilities first, then select a supported bounded request. Never paste keys into prompts, source, URLs, or logs.
3. The signed-in owner lists their keys with GET /api/v1/gate/keys and revokes one with DELETE /api/v1/gate/keys/{key_id}, using their human session, not the consultation key. Subsequent discovery, consultation, reads, and feedback are denied. Already admitted requests are not cancelled; revocation does not erase retained evidence.

Runtime observation and consultation are separate grants. Codex and Claude hook recipes describe observation; a supported host label does not certify execution permissions for that runtime. See developer recipes and the maintained integration examples.

Discover, consult, inspect

All routes below require the explicit consultation grant. This is a public description, not an anonymous tool endpoint. The API base is https://api.warmwinter.io.

GET /api/v1/gate/consultations/capabilities

Discover admitted capabilities and current request limits.

POST /api/v1/gate/consultations

Compute and retain one bounded advisory reading.

GET /api/v1/gate/consultations/{id}

Read a result belonging to the originating grant.

POST /api/v1/gate/consultations/{id}/feedback

Record self-reported usefulness, not an independently verified outcome.

Every request names a capability and a source_ref (1–128 characters: letters, digits, underscore, dot, slash, colon, at-sign or hyphen), plus usefulness_confidence in [0, 1]. Optional task_ref uses the same reference bounds; optional run_id (1–64 letters, digits or hyphens) must belong to this exact runtime grant and organization. Unknown extra fields and nonfinite numbers are rejected.

• queue-pressure: arrival_rate and service_capacity, each in [0, 1e9]; rate_unit is tasks/second, tasks/minute or tasks/hour. Capacity at or below 1e-12 is treated as zero; nonfinite output has an explicit marker rather than a fabricated finite value.
• conservation-balance: required arrays inflows, outflows, generation, consumption, each with at most 32 rates in [0, 1e9]. An explicit empty array declares no flows in that category. One rate_unit applies to all flows: tasks/second, tasks/minute, tasks/hour or items/hour.
• empirical-tail-risk: 1–2048 losses in [0, 1e9], alpha in [0, 0.99], loss_unit tasks, seconds or items, and sample_basis reported_observations, simulation or hypothesis. Alpha is a tail cutoff, not forecast confidence.

# A human supplies this consultation-only key through your environment.
# Discover the deployment's admitted capabilities before selecting one.
curl --fail-with-body https://api.warmwinter.io/api/v1/gate/consultations/capabilities \
  -H "X-Api-Key: $WARMWINTER_CONSULTATION_KEY"

# This POST retains a consultation record. Run only with the owner's consent.
curl --fail-with-body https://api.warmwinter.io/api/v1/gate/consultations \
  -H "X-Api-Key: $WARMWINTER_CONSULTATION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"capability":"queue-pressure","arrival_rate":8,"service_capacity":10,"rate_unit":"tasks/minute","source_ref":"my-task:rates","task_ref":"my-task:capacity","usefulness_confidence":0.6}'

For these declared queue rates, utilization is 0.8 and the native regime is stable. Measurement uncertainty remains unknown. usefulness_confidence is the caller’s forecast of usefulness, not measurement confidence. Read the result’s assumptions, provenance, resource limits, and uncertainty before using it.

Missing, invalid, or revoked keys return 401; a wrong scope or inactive/unbound account returns 403. Inaccessible results or runs return 404. Unsupported or nonfinite inputs return 422; account request limits return 429; withdrawn model admission returns 503. Stop on rejection and ask the owner; do not broaden the grant or automatically retry a new consultation POST.

The current account ceiling is 60 requests per minute across its grants, or a key’s lower limit. This is not a lifetime spending cap. Requests retain supplied inputs, references, and result metadata as account-scoped evidence. Submit only data the owner permits to leave the runtime. Feedback remains self-reported and pending independent outcome; a consultation-only key cannot start arbitrary machine runs.

SDK source and local MCP