Skip to main content

API reference

The platform chart deploys three backend REST APIs for administration and automation. The console uses these APIs.

All three are cluster-internal. The chart creates ClusterIP Services and no ingress, so reach them over Service DNS from inside the cluster, or publish them yourself as described in Deploy the platform.

The ToolHive Registry API is documented separately

The Registry Server is also deployed by this chart, but its API is shared with the open source build and is documented in the Registry Server API reference.

Enterprise Manager​

The Enterprise Manager API covers users, groups, connectors, managed secrets, virtual API keys, budgets, and signed Stacklok CLI configuration.

The running service also self-serves this reference at /api/doc, which is generated from the same source and therefore always matches the version you have deployed.

Two route groups are absent from this specification

The generated specification omits the SCIM provisioning and budget webhook routes. Use /api/doc on the running service for its complete API reference.

API docs by Redocly

Enterprise Manager API (0.1.0)

Download OpenAPI specification:Download

Stacklok Enterprise Manager — unified admin API for configuration delivery, directory, and budget management.

budgets

Budget cells summary

Authorizations:
BearerAuth
query Parameters
scope
string
Enum: "user" "group"

Principal tier filter

subject
string

Subject id prefix match

at
string

Instant the period windows are computed against, RFC 3339 (default now)

cursor
string

Opaque keyset cursor from a previous page

limit
integer

Page size (default 50, max 200, clamped)

Responses

Response samples

Content type
application/json
{
  • "cells": [
    ],
  • "next_cursor": "string"
}

Budget consumption breakdown

One budget's current-period spend broken down by user, model, and provider. The period window is computed server-side (current period only). Each dimension's entries sum to total_used_usd.

Authorizations:
BearerAuth
query Parameters
scope
required
string
Enum: "user" "group"

Principal tier

subject_id
required
string

Budget subject id (OIDC sub for user budgets, group UUID for group budgets)

Responses

Response samples

Content type
application/json
{
  • "by_model": [
    ],
  • "by_provider": [
    ],
  • "by_user": [
    ],
  • "period": "string",
  • "period_end": "string",
  • "period_start": "string",
  • "scope": "string",
  • "subject_id": "string",
  • "total_used_usd": "string"
}

Daily spend series

Zero-filled daily USD totals over the served window, including the current (in-progress) UTC day. from/to echo the bounds actually served after clamping (to at the end of the current UTC day, from at the retention horizon).

Authorizations:
BearerAuth
query Parameters
granularity
string
Value: "day"

Bucket granularity

from
string

Window start, ISO date (default 30 days back, including today)

to
string

Window end (exclusive), ISO date

model
string

Served model of the underlying event, exact match

scope
string
Enum: "user" "group"

Payer tier charged

subject_id
string

Payer charged, exact match

Responses

Response samples

Content type
application/json
{
  • "buckets": [
    ],
  • "from": "string",
  • "granularity": "string",
  • "to": "string"
}

Delete default user budget

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete group budget

Authorizations:
BearerAuth
path Parameters
id
required
string

Group subject_id

header Parameters
If-Match
string

ETag from GET /v1/budgets

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete pricing catalog entry

Remove one (provider, model) rate row outright. There is no revert-to-baseline: the next request for that model is denied at admission as unpriceable. This republishes the ENTIRE remaining catalog as a new operator-dated version, permanently opting this deployment out of baseline updates shipped later.

Authorizations:
BearerAuth
path Parameters
provider
required
string

Literal provider as stored

model
required
string

Model name (may contain '/')

header Parameters
If-Match
required
string

ETag from GET /v1/budgets/pricing or the per-entry GET

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete staged pricing catalog version

Remove a pricing catalog version staged to take effect later, addressed by its exact effective_from. Clears the 409 a staged version causes on every pricing write. A version that has already taken effect cannot be removed and returns 409.

Authorizations:
BearerAuth
path Parameters
effectiveFrom
required
string

Staged version's effective_from, RFC 3339

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete user budget

Authorizations:
BearerAuth
path Parameters
id
required
string

User subject_id

header Parameters
If-Match
string

ETag from GET /v1/budgets

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Get active pricing catalog

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "effective_from": "string",
  • "provider_aliases": {
    },
  • "spec": {
    }
}

Get budgets

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "budgets": [
    ]
}

Get default user budget

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "limit_usd": "string",
  • "period": "string"
}

Get pricing catalog entry

Authorizations:
BearerAuth
path Parameters
provider
required
string

Literal provider as stored

model
required
string

Model name (may contain '/')

Responses

Response samples

Content type
application/json
{
  • "anthropic": {
    },
  • "google": {
    },
  • "model": "string",
  • "openai": {
    },
  • "provider": "string"
}

Group budget breakdown slice

A group budget's current-period spend sliced by one dimension. dimension selects the slice axis; entries sum to total_used_usd.

Authorizations:
BearerAuth
path Parameters
id
required
string

Group subject_id

query Parameters
dimension
required
string
Enum: "user" "model"

Slice axis

Responses

Response samples

Content type
application/json
{
  • "dimension": "string",
  • "entries": [
    ],
  • "period": "string",
  • "period_end": "string",
  • "period_start": "string",
  • "scope": "string",
  • "subject_id": "string",
  • "total_used_usd": "string"
}

List charges

Authorizations:
BearerAuth
query Parameters
from
string

Inclusive event_time lower bound, RFC 3339

to
string

Exclusive event_time upper bound, RFC 3339

model
string

Served model of the underlying event, exact match

scope
string
Enum: "user" "group"

Payer tier charged

subject_id
string

Payer charged, exact match

cursor
string

Opaque keyset cursor from a previous page

limit
integer

Page size (default 50, max 10000, clamped)

Responses

Response samples

Content type
application/json
{
  • "charges": [
    ],
  • "next_cursor": "string"
}

List own charges

Lists the charge records derived from the caller's own usage events, scoped to the verified token subject. A page may contain fewer than limit records even when more data exists; keep following next_cursor until it is absent.

Authorizations:
BearerAuth
query Parameters
from
string

Inclusive event_time lower bound, RFC 3339

to
string

Exclusive event_time upper bound, RFC 3339

model
string

Served model of the underlying event, exact match

cursor
string

Opaque keyset cursor from a previous page

limit
integer

Page size (default 50, max 200, clamped)

Responses

Response samples

Content type
application/json
{
  • "charges": [
    ],
  • "next_cursor": "string"
}

List own usage events

Lists the caller's own usage events, scoped to the verified token subject. A page may contain fewer than limit records even when more data exists; keep following next_cursor until it is absent.

Authorizations:
BearerAuth
query Parameters
from
string

Inclusive event_time lower bound, RFC 3339

to
string

Exclusive event_time upper bound, RFC 3339

model
string

Served model, exact match

outcome
string
Enum: "delivered" "blocked_downstream" "client_disconnect" "upstream_error"

Interaction outcome

cursor
string

Opaque keyset cursor from a previous page

limit
integer

Page size (default 50, max 200, clamped)

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "next_cursor": "string"
}

List usage events

Authorizations:
BearerAuth
query Parameters
from
string

Inclusive event_time lower bound, RFC 3339

to
string

Exclusive event_time upper bound, RFC 3339

model
string

Served model, exact match

auth_subject
string

Verified OIDC subject, exact match

outcome
string
Enum: "delivered" "blocked_downstream" "client_disconnect" "upstream_error"

Interaction outcome

cursor
string

Opaque keyset cursor from a previous page

limit
integer

Page size (default 50, max 10000, clamped)

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "next_cursor": "string"
}

Own budgets summary

The caller's personal day/month cards (absent when no personal budget exists at that period) and every budget cell applicable to them. Group rows expose team aggregates, never teammate records; my_contribution_usd is the caller's own share, folded from their charge records (retention-bounded).

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "budgets": [
    ],
  • "day": {
    },
  • "month": {
    },
  • "subject": "string"
}

Own daily spend series

Authorizations:
BearerAuth
query Parameters
granularity
string
Value: "day"

Bucket granularity

from
string

Window start, ISO date (default 30 days back, including today)

to
string

Window end (exclusive), ISO date

model
string

Served model of the underlying event, exact match

Responses

Response samples

Content type
application/json
{
  • "buckets": [
    ],
  • "from": "string",
  • "granularity": "string",
  • "to": "string"
}

Put default user budget

Authorizations:
BearerAuth
Request Body schema: application/json
required

Default user budget specification

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Put group budget

Authorizations:
BearerAuth
path Parameters
id
required
string

Group subject_id

header Parameters
If-Match
string

ETag from GET /v1/budgets

Request Body schema: application/json
required

Group budget specification

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Put pricing catalog entry

Upsert one (provider, model) rate row. The body must carry exactly one of anthropic / openai / google. This republishes the ENTIRE merged catalog as a new operator-dated version: the first per-entry edit permanently opts this deployment out of built-in pricing baseline updates shipped in later releases, and a model only a newer baseline prices is then denied at admission as unpriceable.

Authorizations:
BearerAuth
path Parameters
provider
required
string

Literal provider to store under

model
required
string

Model name (may contain '/')

header Parameters
If-Match
required
string

ETag from GET /v1/budgets/pricing or the per-entry GET

Request Body schema: application/json
required

Rate block for this entry

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Put user budget

Authorizations:
BearerAuth
path Parameters
id
required
string

User subject_id

header Parameters
If-Match
string

ETag from GET /v1/budgets

Request Body schema: application/json
required

User budget specification

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Set budgets

Authorizations:
BearerAuth
header Parameters
If-Match
string

ETag from GET /v1/budgets

Request Body schema: application/json
required

Complete budget collection

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Spend export (CSV)

A grouped, bucketed rollup of charge records as CSV, sorted bucket ascending then charged_usd descending then group key(s) ascending. A single group_by dimension renders a fixed "group_key" column; two or more render one named column per dimension, in the order given. The served window (after default/retention clamping) is echoed in the X-Spend-Export-From/To response headers. Experiment-gated; 404s when the operator has not enabled it.

Authorizations:
BearerAuth
query Parameters
group_by
string

Comma-separated grouping dimensions, e.g. user,model. Each must be one of user, model, provider, with no repeats. Defaults to user.

granularity
string
Enum: "day" "week" "month"

Bucket width

from
string

Window start, RFC 3339 or YYYY-MM-DD (default 30 days back, including today)

to
string

Window end (exclusive), RFC 3339 or YYYY-MM-DD

model
string

Filter: served model of the underlying event, exact match. Narrows which charges are included; does not change the grouping — use group_by for that

scope
string
Enum: "user" "group"

Filter: payer tier charged

subject_id
string

Filter: payer charged, exact match

Responses

User budget breakdown slice

A user's spend sliced by one dimension. dimension=model is the current-period spend on the user's own budget; dimension=group is every group budget the user belongs to or has contributed to (no single period window). Entries sum to total_used_usd.

Authorizations:
BearerAuth
path Parameters
id
required
string

User subject_id

query Parameters
dimension
required
string
Enum: "model" "group"

Slice axis

Responses

Response samples

Content type
application/json
{
  • "dimension": "string",
  • "entries": [
    ],
  • "period": "string",
  • "period_end": "string",
  • "period_start": "string",
  • "scope": "string",
  • "subject_id": "string",
  • "total_used_usd": "string"
}

config

Get enterprise configuration

Returns the signed enterprise configuration envelope for the calling client.

Authorizations:
BearerAuth
header Parameters
X-Client-Type
required
string
Enum: "toolhive-desktop" "toolhive-cli" "toolhive-cloud-ui"

Client type

X-Client-Version
required
string

Client version (semver, e.g. 1.2.3)

If-None-Match
string

ETag for conditional GET (RFC 7232)

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "degraded_mode": {
    },
  • "etag": "sha256:abc123",
  • "issued_at": "string",
  • "not_after": "string",
  • "refresh_interval": "5m0s",
  • "schema_version": "1",
  • "signature": "string"
}

directory

Add subgroup

Authorizations:
BearerAuth
path Parameters
group_id
required
string

Group UUID

child_id
required
string

Child group UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Add user member

Authorizations:
BearerAuth
path Parameters
group_id
required
string

Group UUID

user_id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Create connector

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

Request Body schema: application/json
required

Connector to create

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "allow_private_ips": true,
  • "auth": {
    },
  • "created_at": "string",
  • "deployment_mode": "string",
  • "description": "string",
  • "endpoint": "string",
  • "gateway_id": "string",
  • "icon_url": "string",
  • "id": "string",
  • "name": "string",
  • "origin": "string",
  • "repository_url": "string",
  • "source_name": "string",
  • "source_namespace": "string",
  • "status": "string",
  • "support_url": "string",
  • "transport": "string",
  • "updated_at": "string",
  • "version": "string"
}

Create connector identity provider

Authorizations:
BearerAuth
Request Body schema: application/json
required

Identity provider to create

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string",
  • "oauth2_config": {
    },
  • "oidc_config": {
    },
  • "provider_type": "string",
  • "registration_mode": "string",
  • "source": "string",
  • "updated_at": "string"
}

Create group

Authorizations:
BearerAuth
Request Body schema: application/json
required

Group to create

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Create managed secret

Authorizations:
BearerAuth
Request Body schema: application/json
required

Managed secret to create

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string",
  • "updated_at": "string"
}

Delete connector

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete connector identity provider

Authorizations:
BearerAuth
path Parameters
id
required
string

IdentityProvider UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete group

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete group metadata

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete managed secret

Authorizations:
BearerAuth
path Parameters
id
required
string

ManagedSecret UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete user metadata

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Get connection

Authorizations:
BearerAuth
path Parameters
id
required
string

Connection UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "created_at": "string",
  • "enabled": true,
  • "gateway_id": "string",
  • "id": "string",
  • "tools_enabled_by_default": true,
  • "tools_exception_list": [
    ],
  • "updated_at": "string",
  • "user_id": "string"
}

Get connector

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "allow_private_ips": true,
  • "auth": {
    },
  • "created_at": "string",
  • "deployment_mode": "string",
  • "description": "string",
  • "endpoint": "string",
  • "gateway_id": "string",
  • "icon_url": "string",
  • "id": "string",
  • "name": "string",
  • "origin": "string",
  • "repository_url": "string",
  • "source_name": "string",
  • "source_namespace": "string",
  • "status": "string",
  • "support_url": "string",
  • "transport": "string",
  • "updated_at": "string",
  • "version": "string"
}

Get connector identity provider

Authorizations:
BearerAuth
path Parameters
id
required
string

IdentityProvider UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string",
  • "oauth2_config": {
    },
  • "oidc_config": {
    },
  • "provider_type": "string",
  • "registration_mode": "string",
  • "source": "string",
  • "updated_at": "string"
}

Get connector policy

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "document": "string",
  • "granted_user_groups": [
    ],
  • "mode": "string"
}

Get group

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Get group members

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

query Parameters
limit
integer

Maximum items per collection (default 50, max 200)

users_cursor
string

Opaque cursor — pages the transitive-users collection forward (mutually exclusive with users_before)

users_before
string

Opaque cursor — pages the transitive-users collection backward (mutually exclusive with users_cursor)

groups_cursor
string

Opaque cursor — pages the direct-child-groups collection forward (mutually exclusive with groups_before)

groups_before
string

Opaque cursor — pages the direct-child-groups collection backward (mutually exclusive with groups_cursor)

active
boolean

Filter the transitive-users collection by active status (direct_child_groups is unaffected)

search
string

Case-insensitive substring search: display_name/user_name/email on the transitive-users collection, display_name/name on the direct-child-groups collection

Responses

Response samples

Content type
application/json
{
  • "direct_child_groups": [
    ],
  • "next_groups_cursor": "string",
  • "next_users_cursor": "string",
  • "prev_groups_cursor": "string",
  • "prev_users_cursor": "string",
  • "transitive_users": [
    ]
}

Get group metadata

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "entity_id": "string",
  • "entity_kind": "string",
  • "metadata": { },
  • "updated_at": "string"
}

Get managed secret

Authorizations:
BearerAuth
path Parameters
id
required
string

ManagedSecret UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string",
  • "updated_at": "string"
}

Get user

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "created_at": "string",
  • "display_name": "string",
  • "email": "string",
  • "id": "string",
  • "photo_url": "string",
  • "source": "string",
  • "updated_at": "string",
  • "user_name": "string"
}

Get user groups

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

Get user metadata

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "entity_id": "string",
  • "entity_kind": "string",
  • "metadata": { },
  • "updated_at": "string"
}

List connector connections

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

List connector identity providers

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

List connectors

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

List discovered MCP servers

Lists the MCP servers the cluster is running as candidates a connector could be admitted from, each carrying the connectors on this gateway that already hold its endpoint.

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

Responses

Response samples

Content type
application/json
{
  • "servers": [
    ]
}

List groups

Authorizations:
BearerAuth
query Parameters
name
string

Filter by group name

display_name
string

Filter by display name

source
string

Filter by provisioning source (e.g. scim)

search
string

Case-insensitive substring search across display_name and name

cursor
string

Opaque pagination cursor — pages forward from here (mutually exclusive with before)

before
string

Opaque pagination cursor — pages backward from here (mutually exclusive with cursor)

limit
integer

Maximum items to return (default 50, max 200)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

List managed secrets

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

List users

Authorizations:
BearerAuth
query Parameters
email
string

Filter by email address

user_name
string

Filter by username

source
string

Filter by provisioning source (e.g. scim)

active
boolean

Filter by active status

search
string

Case-insensitive substring search across display_name, user_name, and email

cursor
string

Opaque pagination cursor — pages forward from here (mutually exclusive with before)

before
string

Opaque pagination cursor — pages backward from here (mutually exclusive with cursor)

limit
integer

Maximum items to return (default 50, max 200)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

Patch group

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

Request Body schema: application/json
required

Fields to update

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Put group metadata

Authorizations:
BearerAuth
path Parameters
id
required
string

Group UUID

Request Body schema:
required

Metadata JSON document

object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Put user metadata

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Request Body schema:
required

Metadata JSON document

object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "error": "string"
}

Remove subgroup

Authorizations:
BearerAuth
path Parameters
group_id
required
string

Group UUID

child_id
required
string

Child group UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Remove user member

Authorizations:
BearerAuth
path Parameters
group_id
required
string

Group UUID

user_id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "description": "string",
  • "display_name": "string",
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "source": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Replace a connector policy's granted user groups

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector UUID

header Parameters
If-Match
required
string

ETag from GET /v1/connectors/{id}/policy

Request Body schema: application/json
required

User group ids

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "document": "string",
  • "granted_user_groups": [
    ],
  • "mode": "string"
}

Revoke a user group's access to a connector

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector UUID

group_id
required
string

User group UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "document": "string",
  • "granted_user_groups": [
    ],
  • "mode": "string"
}

Set a connector policy's Cedar document

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector UUID

Request Body schema: application/json
required

Cedar document

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "document": "string",
  • "granted_user_groups": [
    ],
  • "mode": "string"
}

Switch a connector policy back to structured authoring mode

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "document": "string",
  • "granted_user_groups": [
    ],
  • "mode": "string"
}

Switch a connector policy to Cedar authoring mode

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "document": "string",
  • "granted_user_groups": [
    ],
  • "mode": "string"
}

Update connector

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

id
required
string

Connector UUID

Request Body schema: application/json
required

Connector's new state

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "allow_private_ips": true,
  • "auth": {
    },
  • "created_at": "string",
  • "deployment_mode": "string",
  • "description": "string",
  • "endpoint": "string",
  • "gateway_id": "string",
  • "icon_url": "string",
  • "id": "string",
  • "name": "string",
  • "origin": "string",
  • "repository_url": "string",
  • "source_name": "string",
  • "source_namespace": "string",
  • "status": "string",
  • "support_url": "string",
  • "transport": "string",
  • "updated_at": "string",
  • "version": "string"
}

Update connector identity provider

Authorizations:
BearerAuth
path Parameters
id
required
string

IdentityProvider UUID

Request Body schema: application/json
required

Identity provider's new state

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "id": "string",
  • "name": "string",
  • "oauth2_config": {
    },
  • "oidc_config": {
    },
  • "provider_type": "string",
  • "registration_mode": "string",
  • "source": "string",
  • "updated_at": "string"
}

discovery

OAuth protected resource metadata

Returns RFC 9728 metadata describing this protected resource.

Responses

Response samples

Content type
application/json
{
  • "authorization_servers": [
    ],
  • "bearer_methods_supported": [
    ],
  • "jwks_uri": "string",
  • "resource": "string",
  • "scopes_supported": [
    ]
}

ToolHive configuration discovery

Returns a discovery document for ToolHive client bootstrap.

Responses

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "config_endpoint": "string",
  • "issuer": "string",
  • "jwks_uri": "string",
  • "oauth_protected_resource": "string",
  • "scopes_supported": [
    ]
}

health

Health check

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Readiness check

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Keys

Create a virtual API key

Mints a key tied to the authenticated caller's OIDC identity. The full plaintext secret is returned ONLY in this response — it is never retrievable afterwards. Ownership is derived from the caller's token, not the request body.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Key creation parameters

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "key": {
    },
  • "secret": "string"
}

Disable one of the caller's virtual API keys

Temporarily deactivates a key. Reversible via the enable endpoint, unlike revocation.

Authorizations:
BearerAuth
path Parameters
id
required
string

Key short ID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Get one of the caller's virtual API keys

Never includes key secrets or hashes. Returns 404 (not 403) when the id exists but is owned by another caller, so key existence is not leaked across owners.

Authorizations:
BearerAuth
path Parameters
id
required
string

Key short ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "expires_at": "string",
  • "id": "string",
  • "last_used_at": "string",
  • "metadata": {
    },
  • "name": "string",
  • "owner_ref": "string",
  • "prefix": "string",
  • "status": "string"
}

List the caller's virtual API keys

Returns every key owned by the authenticated caller. Never includes key secrets or hashes.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Re-enable one of the caller's disabled virtual API keys

Moves a disabled key back to active. Re-enabling a revoked key is rejected with 409 — revocation is permanent.

Authorizations:
BearerAuth
path Parameters
id
required
string

Key short ID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Revoke one of the caller's virtual API keys

Permanently invalidates the key. This cannot be undone — a revoked key can never be re-enabled.

Authorizations:
BearerAuth
path Parameters
id
required
string

Key short ID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Rotate one of the caller's virtual API keys

Generates a new secret for the same key ID. The old secret keeps validating for a 24h grace period so in-flight callers can pick up the new secret. The new plaintext secret is returned only once.

Authorizations:
BearerAuth
path Parameters
id
required
string

Key short ID

Responses

Response samples

Content type
application/json
{
  • "key": {
    },
  • "secret": "string"
}

Me

Create my connection

Authorizations:
BearerAuth
Request Body schema: application/json
required

Connection to create

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "created_at": "string",
  • "enabled": true,
  • "gateway_id": "string",
  • "id": "string",
  • "tools_enabled_by_default": true,
  • "tools_exception_list": [
    ],
  • "updated_at": "string",
  • "user_id": "string"
}

Delete my connection

Authorizations:
BearerAuth
path Parameters
id
required
string

Connection UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Enable or disable my connection

Authorizations:
BearerAuth
path Parameters
id
required
string

Connection UUID

Request Body schema: application/json
required

New enablement

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "created_at": "string",
  • "enabled": true,
  • "gateway_id": "string",
  • "id": "string",
  • "tools_enabled_by_default": true,
  • "tools_exception_list": [
    ],
  • "updated_at": "string",
  • "user_id": "string"
}

Get a Connector visible to me

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

id
required
string

Connector UUID

Responses

Response samples

Content type
application/json
{
  • "allow_private_ips": true,
  • "auth": {
    },
  • "created_at": "string",
  • "deployment_mode": "string",
  • "description": "string",
  • "endpoint": "string",
  • "gateway_id": "string",
  • "icon_url": "string",
  • "id": "string",
  • "name": "string",
  • "origin": "string",
  • "repository_url": "string",
  • "source_name": "string",
  • "source_namespace": "string",
  • "status": "string",
  • "support_url": "string",
  • "transport": "string",
  • "updated_at": "string",
  • "version": "string"
}

Get my connection

Authorizations:
BearerAuth
path Parameters
id
required
string

Connection UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "created_at": "string",
  • "enabled": true,
  • "gateway_id": "string",
  • "id": "string",
  • "tools_enabled_by_default": true,
  • "tools_exception_list": [
    ],
  • "updated_at": "string",
  • "user_id": "string"
}

Get the caller's own directory profile

Returns the authenticated caller's directory profile and transitive group membership, resolved from their verified token rather than a path parameter. An authenticated caller with no directory binding (never provisioned, or deactivated) gets 200 with an empty group list, not a 404 — a miss is not a failure. subject and issuer are always present since they come from the verified token; echoing issuer lets a caller self-diagnose a cross-issuer provisioning gap.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "display_name": "string",
  • "email": "string",
  • "groups": [
    ],
  • "id": "string",
  • "issuer": "string",
  • "source": "string",
  • "subject": "string",
  • "user_name": "string"
}

List Connectors visible to me

Authorizations:
BearerAuth
path Parameters
gateway_id
required
string

Connector-gateway install id

query Parameters
cursor
string

Opaque pagination cursor — pages forward from here (mutually exclusive with before)

before
string

Opaque pagination cursor — pages backward from here (mutually exclusive with cursor)

limit
integer

Maximum items to return (default 20, max 200)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

List my connections

Authorizations:
BearerAuth
query Parameters
gateway_id
string

Narrow to Connections on one gateway install

cursor
string

Opaque pagination cursor — pages forward from here (mutually exclusive with before)

before
string

Opaque pagination cursor — pages backward from here (mutually exclusive with cursor)

limit
integer

Maximum items to return (default 20, max 200)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "string"
}

Set my connection's tool narrowing

Authorizations:
BearerAuth
path Parameters
id
required
string

Connection UUID

Request Body schema: application/json
required

New tool policy

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "created_at": "string",
  • "enabled": true,
  • "gateway_id": "string",
  • "id": "string",
  • "tools_enabled_by_default": true,
  • "tools_exception_list": [
    ],
  • "updated_at": "string",
  • "user_id": "string"
}

metering

Connector tool-call activity

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector id

query Parameters
gateway_id
required
string

connector-gateway instance id

user_id
string

Platform user id (UUID); narrows to one user's calls

outcome
string
Enum: "ok" "error"

Outcome filter

decision
string
Enum: "allowed" "denied"

Decision filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

cursor
string

Opaque keyset cursor from a previous page, pages forward (older)

before
string

Opaque keyset cursor from a previous page, pages backward (newer); mutually exclusive with cursor

limit
integer

Page size (default 50, max 500, clamped)

Responses

Response samples

Content type
application/json
{
  • "next_cursor": "string",
  • "prev_cursor": "string",
  • "records": [
    ]
}

Connector usage

Authorizations:
BearerAuth
path Parameters
id
required
string

Connector id

query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "connector_name": "string",
  • "group_series": [
    ],
  • "tool_call_count": 0
}

My tool-call activity

Authorizations:
BearerAuth
query Parameters
gateway_id
required
string

connector-gateway instance id

connector_id
required
string

Connector id

outcome
string
Enum: "ok" "error"

Outcome filter

decision
string
Enum: "allowed" "denied"

Decision filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

cursor
string

Opaque keyset cursor from a previous page, pages forward (older)

before
string

Opaque keyset cursor from a previous page, pages backward (newer); mutually exclusive with cursor

limit
integer

Page size (default 50, max 500, clamped)

Responses

Response samples

Content type
application/json
{
  • "next_cursor": "string",
  • "prev_cursor": "string",
  • "records": [
    ]
}

Per-event usage export

Authorizations:
BearerAuth
query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

cursor
string

Opaque keyset cursor from a previous page

limit
integer

Page size (default 50, max 500, clamped)

Responses

Response samples

Content type
application/json
{
  • "checkpoints": [
    ],
  • "next_cursor": "string",
  • "records": [
    ]
}

Top connectors

Authorizations:
BearerAuth
query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

limit
integer

Max entries (default 10, max 100, clamped)

Responses

Response samples

Content type
application/json
{
  • "connectors": [
    ]
}

Top tools

Authorizations:
BearerAuth
query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

limit
integer

Max entries (default 10, max 100, clamped)

Responses

Response samples

Content type
application/json
{
  • "tools": [
    ]
}

Usage summary

Authorizations:
BearerAuth
query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

Responses

Response samples

Content type
application/json
{
  • "active_user_count": 0,
  • "tool_call_count": 0
}

Usage time series

Authorizations:
BearerAuth
query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
string

Window start, RFC 3339 (default: unbounded)

end
string

Window end, RFC 3339, exclusive (default: unbounded)

dimension
string
Enum: "environment" "tool" "decision" "connector"

Breakdown dimension

Responses

Response samples

Content type
application/json
{
  • "bucket_width_seconds": 0,
  • "buckets": [
    ],
  • "dimension": "string"
}

User usage

Authorizations:
BearerAuth
path Parameters
id
required
string

Platform user id (UUID)

query Parameters
gateway_id
required
string

connector-gateway instance id

environment
string

Deployment environment filter

start
required
string

Window start, RFC 3339

end
required
string

Window end, RFC 3339, exclusive

Responses

Response samples

Content type
application/json
{
  • "connectors": [
    ],
  • "last_activity": "string",
  • "series": [
    ],
  • "tool_call_count": 0,
  • "user_id": "string"
}

security

Get JWKS

Returns the JSON Web Key Set for verifying signed config envelopes.

Responses

Response samples

Content type
application/json
{ }

Connector Gateway​

The Connector Gateway API covers connector enablement and per-user authorization state. See Configure the Connector Gateway.

API docs by Redocly

Connector Gateway API (0.1.0)

Download OpenAPI specification:Download

Stacklok connector-gateway control-plane — user-self API to view and toggle the caller's MCP connectors.

Clear a connector's explicit state (revert to default)

path Parameters
connector_id
required
string

Connector (vmcp backend) ID

header Parameters
If-Match
required
string

Current connector ETag. Missing -> 428; stale -> 412.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Get one connector's current state

path Parameters
connector_id
required
string

Connector (vmcp backend) ID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "enabled": true,
  • "updated_at": "string"
}

Get one connector's upstream connection status

path Parameters
connector_id
required
string

Connector id: a Directory connectors.id under the toggle, the vmcp backend id otherwise

Responses

Response samples

Content type
application/json
{
  • "connection_status": "ready"
}

Get the caller's gateway view

Responses

Response samples

Content type
application/json
{
  • "connectors": [
    ],
  • "connectors_retired": true,
  • "endpoint_url": "string"
}

List a Connector's Tools

path Parameters
connector_id
required
string

Connector (Directory connectors.id) UUID

Responses

Response samples

Content type
application/json
{
  • "tools": [
    ]
}

List every connector's upstream connection status

Responses

Response samples

Content type
application/json
{
  • "statuses": [
    ]
}

List the caller's connectors (catalog joined with per-user state)

Responses

Response samples

Content type
application/json
{
  • "connectors": [
    ]
}

Set a connector's enable/disable state

path Parameters
connector_id
required
string

Connector (vmcp backend) ID

header Parameters
If-Match
required
string

Current connector ETag. Missing -> 428; stale -> 412.

Request Body schema: application/json
required

Desired state

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "enabled": true,
  • "updated_at": "string"
}

Start a connector's upstream connect flow

path Parameters
connector_id
required
string

Connector (vmcp backend) ID

Responses

Response samples

Content type
application/json
{
  • "authorize_url": "string"
}

AI Gateway management​

The AI Gateway management API updates custom resources through the Kubernetes API. See Configure the AI Gateway.

For task-oriented AI Gateway configuration, see AI Gateway.

API docs by Redocly

AI Gateway Management API (0.1.0)

Download OpenAPI specification:Download

URL: https://docs.stacklok.com/platform License: Apache-2.0

Admin-scoped HTTP API backing the help-desk UI. The server is a thin facade over the Kubernetes API: write endpoints translate to typed AIPolicy CR create/update/delete calls via controller-runtime, and introspection endpoints read from the same cache. No parallel store.

Scope

Each API server instance is bound to exactly one Kubernetes namespace (configured via operator flag) and all AIPolicy CRs live in that namespace. The namespace is therefore not in the URL path; multi- namespace deployments run multiple API instances. A future major version may introduce /v1/namespaces/{ns}/... if multi-tenant scoping is required; clients should treat the current paths as namespace-local.

Authentication and authorization

All requests require a bearer JWT validated against the OIDC provider configured on the target AIGateway (spec.auth.oidc). Role checks are performed per path; role names (admin, policyEditor, authenticated) are conventional and are themselves resolved against AIGateway.spec.auth.authz.roles, which maps each role name to a list of principal matchers.

Concurrency control

GET on a single policy returns an ETag header whose value is the quoted metadata.resourceVersion. PATCH and DELETE both require the If-Match header. Concurrency failures use distinct status codes so the UI can branch without parsing error strings:

  • 428 Precondition Required (RFC 6585) — If-Match header is missing. This is a client bug; UIs should surface it as a dev-tools error rather than a user-facing "policy changed" dialog.
  • 412 Precondition Failed (RFC 7232) — If-Match was sent but the value no longer matches the server's resourceVersion (another admin edited concurrently). UIs should re-fetch and offer a merge/overwrite flow.
  • 409 Conflict — reserved for POST with a metadata.name that already exists. UIs should prompt for a different name.

Catalog

List all MCP servers visible to the gateway.

Forward-compatible; always returns an empty items array in Phase 8. Enforcement lands in a later phase.

Authorizations:
BearerAuth
header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List all models visible to the gateway in the current namespace.

Derived from the owning AIGateway's spec.routes[].match.model. Deduplicated and sorted by model id, OpenAI-shaped (object:"list", data[]) to match the data-plane GET /v1/models intercept.

Authorizations:
BearerAuth
header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list"
}

Return the owning gateway's identity.

Returns the AIGateway name and namespace this api-key-service serves. Sourced from the operator-injected GATEWAY_NAME / GATEWAY_NAMESPACE — authoritative and unambiguous.

Authorizations:
BearerAuth
header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "name": "prod-gateway",
  • "namespace": "llm-gateway"
}

Introspection

Return the caller's identity and resolved policy bindings.

Returns subject, groups, resolved roles, the set of AIPolicies whose principalMatchers the caller satisfies, and the union of models granted by those policies' budgets. Matched-only — the response never includes policies the caller does not match.

Authorizations:
BearerAuth
header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "email": "admin@example.com",
  • "groups": [
    ],
  • "matchedPolicies": [
    ],
  • "models": [
    ],
  • "roles": [
    ],
  • "subject": "github|42",
  • "unrestrictedModels": false
}

Policies

Create a new AIPolicy.

Use metadata.name as the idempotency key. Retrying a POST with the same name returns 409 Conflict; clients should treat this as either a duplicate submission (succeeded previously) or a deliberate collision (surface to the user).

Authorizations:
BearerAuth
header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Request Body schema: application/json
required

Full AIPolicy object. metadata.namespace is ignored; the server's configured namespace wins.

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Delete an AIPolicy.

If-Match is required; missing returns 428 and stale returns 412, so accidental wipes during a concurrent edit never silently succeed.

Authorizations:
BearerAuth
path Parameters
name
required
string

Policy name.

header Parameters
If-Match
required
string

Quoted resourceVersion from a preceding GET. Required.

X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "error": "unauthenticated",
  • "requestId": "e7c61d23-0b1a-4d3e-8a0b-18d4f1d7e2c3",
  • "violations": [
    ]
}

Get a single AIPolicy by name.

Authorizations:
BearerAuth
path Parameters
name
required
string

Policy name (DNS-1123 subdomain, max 253 chars).

header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

List AIPolicies in the configured namespace.

Returns a page of AIPolicies. limit caps the underlying apiserver page size (max 500; larger values are clamped). pageToken resumes a prior list at the next page boundary. labelSelector accepts the standard apimachinery selector syntax (e.g., team=eng,tier!=internal). gatewayRef is a post-list filter applied to the returned page; when used with limit, the returned page may contain fewer matches than the limit — callers must keep paging while nextPageToken is non-empty to enumerate every match. When labelSelector is set, the apiserver omits remainingItemCount (per the Kubernetes API spec: the remaining count is unknown for selector-filtered lists), so the field will be absent on the response regardless of how many pages remain. A present-but-empty value for limit, pageToken, or labelSelector (e.g., ?limit=) is equivalent to the parameter being absent and uses the server default for that parameter — empty is not "explicitly clear this filter".

Authorizations:
BearerAuth
query Parameters
limit
integer

Max items per page (1..500). Values above 500 are clamped to 500; 0 or omitted uses the server default (500).

pageToken
string

Opaque continue token from a previous response. An expired or malformed token returns 400; restart the list from page one.

labelSelector
string

Kubernetes label selector (e.g., team=eng,tier!=internal). Malformed selectors return 400.

gatewayRef
string

Restrict to policies targeting this AIGateway name. Applied as a post-list filter; may reduce the returned page size below limit.

header Parameters
X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Responses

Response samples

Content type
application/json
{
  • "apiVersion": "string",
  • "items": [
    ],
  • "kind": "string",
  • "nextPageToken": "string",
  • "remainingItemCount": 0
}

Update an AIPolicy using JSON merge patch.

Patches are applied against spec only; any status or metadata.resourceVersion sent in the body is ignored (use If-Match for optimistic concurrency). spec.gatewayRef is immutable after creation; attempting to modify it returns 422.

Authorizations:
BearerAuth
path Parameters
name
required
string

Policy name.

header Parameters
If-Match
required
string

Quoted resourceVersion from a preceding GET. Required: missing returns 428 Precondition Required; stale returns 412 Precondition Failed.

X-Request-Id
string

Correlation ID; echoed on responses and included in audit records.

Request Body schema:
required

RFC 7396 JSON merge patch; only /spec may be patched.

object (AIPolicySpecPatch)
description
string <= 2048 characters
object (MCPPolicy)

MCPPolicy binds matched principals to MCP servers. Forward-compatible; not enforced in Phase 8.

Array of objects (PrincipalMatcher)

When present, replaces the stored principalMatchers entirely. 1..32 entries.

Responses

Request samples

Content type
{
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "apiVersion": "string",
  • "kind": "string",
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}