This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

API Reference

AI Gateway endpoints, input fields, and output fields.

1: Health
2: Administration
3: Policy

The AI Gateway API is exposed under /pty/federated-guardrails/v1.

Each API page lists the method, URL, input fields, and output fields for its endpoints. When an admin token is configured, send it as Authorization: Bearer <admin-token>. Mutating admin requests must also include X-Requested-With: XMLHttpRequest for CSRF protection. Cedar policy is managed by Policy; the Cedar endpoints expose or synchronize the active policy and are not local policy-file workflows.

The machine-readable contract is available here: Download the AI Gateway OpenAPI specification.

1 - Health

Health and readiness endpoints.

The health and readiness endpoints report the status of the gateway instance that handles the request. They are not cluster-wide checks; a request through a load-balanced service may reach any replica.

Health

Return the current health status of the gateway process.

Method	URL
`GET`	`/pty/federated-guardrails/v1/health`

Input Fields

None.

Output Fields

Field	Type	Description
`status`	string	Gateway process health status.

Ready

Return the current readiness status of the gateway process, including verification of the YAML policy, scanners, and policy state.

Method	URL
`GET`	`/pty/federated-guardrails/v1/ready`

Input Fields

None.

Output Fields

Readiness status indicating whether the YAML policy, scanners, and policy state are acceptable.

Response Codes

The health and readiness endpoints return the following HTTP status codes to indicate the outcome of a request.

Code	Description
`200`	Request completed successfully.
`503`	The gateway is not ready.

2 - Administration

Gateway administration endpoints and their per-instance behavior.

Administration endpoints operate on one gateway instance at a time. A request routed through a load-balanced service may reach any replica; these endpoints do not provide cluster-wide state. When an admin token is configured, send Authorization: Bearer <admin-token>. POST, PUT, PATCH, and DELETE requests also require X-Requested-With: XMLHttpRequest.

Reload Policy

Reload the YAML policy on the gateway instance that receives the request.

Method	URL
`POST`	`/pty/federated-guardrails/v1/admin/reload`

Input Fields

None.

Output Fields

Policy reload status.

Circuit Breakers

Return the circuit-breaker status for each configured scanner on this instance.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/circuit-breakers`

Input Fields

None.

Output Fields

Circuit-breaker status for configured scanners on this instance.

SLA

Report SLA metrics for this instance only, including service availability and latency adherence.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/sla`

Input Fields

None.

Output Fields

Per-instance SLA metrics, including availability and latency adherence.

Statistics

Return summary metrics from this instance only.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/stats`

Input Fields

None.

Output Fields

Per-instance summary metrics.

Streaming Latency Estimate

Return per-profile estimated scan latency percentiles for streaming requests handled by this instance.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/streaming/latency-estimate`

Input Fields

None.

Output Fields

Per-profile estimated P50, P95, and P99 scan latency for this instance.

Response Codes

Code	Description
`200`	Request completed successfully.
`401`	Authentication is missing or invalid.
`403`	The authenticated user is not authorized.
`500`	The administration operation failed.

3 - Policy

YAML policy inspection and scanner validation endpoints.

Policy endpoints operate on one gateway instance at a time. A request routed through a load-balanced service may reach any replica. Manage YAML policy through Helm values and the gateway ConfigMap; Cedar policy comes from Policy. When an admin token is configured, send Authorization: Bearer <admin-token>. Mutating requests also require X-Requested-With: XMLHttpRequest.

Get YAML Policy

Retrieve the active YAML policy from the gateway instance handling the request. Use the deployment’s Helm values and ConfigMap to manage policy changes.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/policy`

Input Fields

None. Requires the admin token when configured.

Output Fields

The active YAML policy as JSON, including scanner definitions, profiles, routing, and upstream configuration.

Validate Scanners

Probe each configured remote scanner on the instance handling the request to verify connectivity and response-format compatibility.

Method	URL
`POST`	`/pty/federated-guardrails/v1/admin/policy/validate-scanners`

Input Fields

None. The gateway sends a probe request to each remote scanner.

Output Fields

Scanner connectivity and response-format validation results for this instance.

List Scanners

Return the scanners configured on the instance handling the request, along with their types.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/policy/scanners`

Input Fields

None.

Output Fields

Configured scanners and their types.

List Profiles

Return the policy profiles configured on the instance handling the request.

Method	URL
`GET`	`/pty/federated-guardrails/v1/admin/policy/profiles`

Input Fields

None.

Output Fields

Configured policy profiles and their scanner configuration.

Response Codes

Code	Description
`200`	Request completed successfully.
`401`	Authentication is missing or invalid.
`403`	The authenticated user is not authorized.
`404`	The requested resource or policy was not found.
`422`	Request validation failed.
`500`	The policy operation failed.