# Telemetry and optimisation

Report the calls made outside the gateway, pick a model for a request, look up and store cached answers, check an agent for a loop, compress long content and query the provider marketplace.

[All of the API reference](https://www.azothos.ai/docs/api)

> Route summaries and field names are written in English, here and in the file.

## /api/ingest

### POST /api/ingest

Ingest AI usage events

- **Authentication** — API key
- **Key scope** — `ingest:write`
- **Body** — `events` (required)
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `402` [budget_exceeded](https://www.azothos.ai/docs/errors#budget_exceeded) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed), [eu_storage_unavailable](https://www.azothos.ai/docs/errors#eu_storage_unavailable) · `413` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `429` [ingest_queue_full](https://www.azothos.ai/docs/errors#ingest_queue_full) · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `503` [service_unavailable](https://www.azothos.ai/docs/errors#service_unavailable) · `504`

## /api/arbiter

### POST /api/arbiter/route

Select optimal model for a request

- **Authentication** — API key
- **Key scope** — `inference:write`
- **Body** — `agentId` · `promptTokens` · `mode` · `qualityFloor` · `latencyCeilingMs` · `budgetUsd` · `candidates`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `402` [budget_exceeded](https://www.azothos.ai/docs/errors#budget_exceeded) · `403` [policy_blocked](https://www.azothos.ai/docs/errors#policy_blocked), [sovereignty_blocked](https://www.azothos.ai/docs/errors#sovereignty_blocked), [jurisdiction_blocked](https://www.azothos.ai/docs/errors#jurisdiction_blocked), [kill_switch_active](https://www.azothos.ai/docs/errors#kill_switch_active), [human_review_not_resumable](https://www.azothos.ai/docs/errors#human_review_not_resumable), [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `503` [budget_unavailable](https://www.azothos.ai/docs/errors#budget_unavailable), [governance_error](https://www.azothos.ai/docs/errors#governance_error)

## /api/cache

### POST /api/cache/lookup

Look up a cached answer for a prompt

- **Authentication** — API key
- **Key scope** — `cache:read`
- **Body** — `prompt` (required) · `threshold` · `model`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error)

### POST /api/cache/store

Store a prompt and its answer in the cache

- **Authentication** — API key
- **Key scope** — `cache:write`
- **Body** — `prompt` (required) · `response` (required) · `model` (required) · `provider` (required) · `costUsd` · `ttlMs`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error)

## /api/loops

### POST /api/loops/check

Check an agent for a loop, reset its counters, or read its state

- **Authentication** — API key
- **Key scope** — `advisory:read`
- **Body** — `action` · `agentId` (required) · `workflowId` · `prompt` · `model` · `costUsd`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error)

## /api/v1/compress

### POST /api/v1/compress

Compress long reasoning content (levels L1 to L3)

- **Authentication** — API key
- **Key scope** — `advisory:read`
- **Module** — Served where the deployment runs `FEATURE_CCE`.
- **Body** — `content` (required) · `level` · `agentId` · `workflowId` · `traceId`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `501` [feature_disabled](https://www.azothos.ai/docs/errors#feature_disabled)

## /api/v1/reconstruct

### POST /api/v1/reconstruct

Reconstruct compressed content from its id

- **Authentication** — API key
- **Key scope** — `advisory:read`
- **Module** — Served where the deployment runs `FEATURE_CCE`.
- **Body** — `cognitiveStateId` (required)
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed) · `404` [not_found](https://www.azothos.ai/docs/errors#not_found) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `501` [feature_disabled](https://www.azothos.ai/docs/errors#feature_disabled)

## /api/v1/marketplace

### GET /api/v1/marketplace

The best-fit model of the provider marketplace for your constraints

- **Authentication** — API key
- **Key scope** — `advisory:read`
- **Module** — Served where the deployment runs `FEATURE_MARKETPLACE`.
- **Parameters** — `mode` · `maxCostPer1k` · `maxLatencyMs` · `minQuality` · `requiresVision` · `requiresTools` · `minContextWindow`
- **Answers** — `200` · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed) · `404` · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `501` [feature_disabled](https://www.azothos.ai/docs/errors#feature_disabled)
