Gateway

Catalog, health, usage

Every request needs a credential — see Authentication.

Method	Path	Summary
`GET`	`/sandbox/healthz`	Gateway aggregated health
`GET`	`/sandbox/v1/catalog`	Execution catalog (languages, agents, profiles, desktop_apps)
`GET`	`/sandbox/v1/providers`	Legacy Sandbox provider inventory (informational)
`GET`	`/sandbox/v1/quota`	Effective concurrency quota and current project usage
`GET`	`/sandbox/v1/usage/summary`	Project-scoped latency percentiles (p50/p95/p99)

Common headers

Accepted on every endpoint on this page.

Name	In	Type	Required	Description
`x-correlation-id`	header	string	no	End-to-end correlation id for this eval run. When set, the gateway and downstream services honor it verbatim in logs, Cloud Trace span attributes, async job payloads, and Langfuse trace.id. When omitted, the gateway generates a ULID and echoes it on the response.

Endpoints

Gateway aggregated health

GET /sandbox/healthz

Responses

Status	Description	Body
`200`	Successful Response	object

Execution catalog (languages, agents, profiles, desktop_apps)

GET /sandbox/v1/catalog

Parameters

Name	In	Type	Required	Description
`kind`	query	string \| null	no

Responses

Status	Description	Body
`200`	Execution catalog entries	any
`422`	Validation Error	HTTPValidationError

Example response:

{
  "items": [
    {
      "id": "oracle",
      "kind": "agent",
      "tier": 1
    },
    {
      "id": "opencode",
      "kind": "agent",
      "tier": 1
    }
  ],
  "count": 2
}

Legacy Sandbox provider inventory (informational)

GET /sandbox/v1/providers

Legacy inventory of providers stored in the Sandbox credential plane.

When SANDBOX_LLM_EGRESS=gateway (credential plane off), this list is often empty or the route returns 503 — LLM BYOK then lives on LLM Gateway. When KeyHive is enabled (SANDBOX_CREDENTIAL_BACKEND=keyhive), inventory reflects leased providers for the caller's tenant:project.

Tenancy comes from :func:resolve_scope (no shared fallback).

Responses

Status	Description	Body
`200`	Successful Response	any

Effective concurrency quota and current project usage

GET /sandbox/v1/quota

Responses

Status	Description	Body
`200`	Successful Response	any

Project-scoped latency percentiles (p50/p95/p99)

GET /sandbox/v1/usage/summary

Parameters

Name	In	Type	Required	Description
`X-Sandbox-Project-Id`	header	string \| null	no	Project to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
`X-Sandbox-Tenant-Id`	header	string \| null	no	Tenant for this request. Must match the credential's tenant when the credential carries one.

Responses

Status	Description	Body
`200`	Successful Response	object
`422`	Validation Error	HTTPValidationError

Schemas

The object shapes referenced above.

HTTPValidationError

Field	Type	Required	Description
`detail`	ValidationError[]	no

ValidationError

Field	Type	Required
`loc`	string \| integer[]	yes
`msg`	string	yes
`type`	string	yes
`input`	any	no
`ctx`	object	no

Machine-readable spec: OpenAPI YAML.

Gateway

On this page