Skip to main content

Enterprise Manager API reference

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.

Base URL​

The REST API uses the Service's HTTP port (service.port, default 80). The same Service also exposes gRPC and webhook ports for other integrations. For an externally exposed deployment, use the Enterprise Manager URL configured as resourceURL, including any path prefix your ingress requires.

With the default Service name and port, the in-cluster base URL is:

http://<RELEASE_NAME>-enterprise-manager.<NAMESPACE>.svc:80

<RELEASE_NAME> is your platform Helm release name. Helm name overrides can change the Service name, and values overrides can change the port. Check your installed Services:

kubectl get svc -n <NAMESPACE>

For a local connection, forward the Service's HTTP port:

kubectl port-forward -n <NAMESPACE> svc/<SERVICE_NAME> 8080:80

Replace <SERVICE_NAME> with the installed Service name. Keep the command running in a separate terminal. Your local base URL is http://localhost:8080. Append each endpoint path to the base URL once; for example, http://localhost:8080/v1/me/connections. API authentication still applies when using a port-forward.

For external access, ask your platform administrator for the URL routed to the Service above. See Expose the platform endpoints for the routing setup.

The request examples below use http://localhost:8080, which matches the port-forward above. For calls from inside the cluster or through an external endpoint, replace that address with your deployment's base URL.

Endpoints​

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 (directory platform user UUID for user budgets, directory 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

Withdraw one (provider, model) rate. The entry is kept as an unpriced tombstone rather than removed, so a later baseline refresh cannot resurrect the rate; the next request for that model is denied at admission as unpriceable. Use POST .../revert to hand the rate back to the shipped baseline. This republishes the ENTIRE merged catalog as a new operator-dated version, but every other rate keeps its ownership and a later release's baseline refresh still reaches the ones nobody pinned.

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 one pricing catalog version

Return the pricing catalog version occupying exactly the given effective_from — active, historical, or staged. Same body shape as GET /v1/budgets/pricing so two versions can be diffed through one decoder.

Authorizations:
BearerAuth
path Parameters
effectiveFrom
required
string

Version's effective_from, RFC 3339

Responses

Response samples

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

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": {
    },
  • "managedBy": "string",
  • "model": "string",
  • "openai": {
    },
  • "provider": "string",
  • "unpriced": true
}

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 pricing catalog versions

List the published pricing catalog versions, newest first, with provenance only (no rate tables). Address one of them by its effective_from on GET /v1/budgets/pricing/versions/{effectiveFrom}.

Authorizations:
BearerAuth

Responses

Response samples

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

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 period-to-date share of that cell, exact for the whole of the cell's period.

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, but only the entry it writes becomes operator-managed: every other rate keeps its ownership and a later release's baseline refresh still reaches the ones nobody pinned. Use POST .../revert to hand this rate back.

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"
}

Revert pricing catalog entry to the shipped baseline

Hand one (provider, model) rate back to the built-in pricing baseline: the baseline's current rates are written into the entry, ownership is recorded as the baseline's, and any tombstone is cleared. This is the remedy for a rate pinned by mistake — a pinned rate is otherwise immune to baseline refreshes. Refused 409 when the shipped baseline does not price the pair, since there is no rate to restore.

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"
}

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

Spend export by conversation label (CSV)

The spend export broken down by conversation label, as CSV, sorted bucket ascending then charged_usd descending then group key(s) ascending. Columns are bucket, one per group_by dimension in the order given, then facet and label, then charge_count and charged_usd. Rows do NOT partition total spend: a session carries one label per facet, so summing either measure across more than one facet multiplies it by the facet count, charge_count exactly as much as charged_usd — pass facet to narrow the export to one. Under a facet filter every row carries that facet, coverage rows included, so pivoting on it is safe. Charges with no label are still counted, under a label naming why: (no-session), (uncaptured), (unclassified) or (unset). 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. The facet and label columns are always present in addition to these

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

facet
string

Filter: restrict the label column to this facet's labels, exact match. The facet vocabulary is operator configuration, so an unknown value yields an empty result rather than an error. Sessions classified without a label for this facet are still counted, under (unset)

model
string

Filter: served model of the underlying event, exact match

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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Clear a group's tool restriction on a connector

Authorizations:
BearerAuth
path Parameters
connector_id
required
string

Connector UUID

group_id
required
string

UserGroup UUID

header Parameters
If-Match
required
string

ETag from GET .../tool-restriction

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "group_id": "string",
  • "restriction_mode": "string",
  • "tool_ids": [
    ],
  • "version": 0
}

Create a Model Set

Authorizations:
BearerAuth
Request Body schema: application/json
required

Model Set

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "string",
  • "kind": "authored",
  • "member_count": 0,
  • "model_ids": [
    ],
  • "name": "string",
  • "unrestricted": true,
  • "version": 0
}

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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "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 a Model Set

Authorizations:
BearerAuth
path Parameters
id
required
string

Model Set UUID

header Parameters
If-Match
required
string

ETag from GET /v1/model-sets/{id}

Responses

Response samples

Content type
application/json
{
  • "error": "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"
}

Discover connector identity provider OAuth metadata

Probes an MCP server and returns its RFC 9728 protected-resource and RFC 8414 authorization-server metadata.

Authorizations:
BearerAuth
Request Body schema: application/json
required

MCP server to inspect

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "authorization_endpoint": "string",
  • "authorization_server": "string",
  • "discovery_url": "string",
  • "mcp_url": "string",
  • "registration_endpoint": "string",
  • "resource": "string",
  • "resource_metadata_url": "string",
  • "scopes_supported": [
    ],
  • "token_endpoint": "string",
  • "token_endpoint_auth_methods_supported": [
    ]
}

Explain a User's effective model access

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

Content type
application/json
{
  • "sets": [
    ],
  • "unrestricted": true
}

Get a group's tool restriction on a connector

Authorizations:
BearerAuth
path Parameters
connector_id
required
string

Connector UUID

group_id
required
string

UserGroup UUID

Responses

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "group_id": "string",
  • "restriction_mode": "string",
  • "tool_ids": [
    ],
  • "version": 0
}

Get a Model Set

Authorizations:
BearerAuth
path Parameters
id
required
string

Model Set UUID

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "string",
  • "kind": "authored",
  • "member_count": 0,
  • "model_ids": [
    ],
  • "name": "string",
  • "unrestricted": true,
  • "version": 0
}

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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "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 Model Sets

Authorizations:
BearerAuth
query Parameters
search
string

Case-insensitive substring match on name

cursor
string

Opaque pagination 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 the Model Sets granted directly to a User

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

Responses

Response samples

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

List the Model Sets granted to a UserGroup

Authorizations:
BearerAuth
path Parameters
id
required
string

UserGroup UUID

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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Preview what deleting a Model Set would remove

Authorizations:
BearerAuth
path Parameters
id
required
string

Model Set UUID

query Parameters
kind
string
Enum: "user" "group"

Restrict subjects to one kind

search
string

Case-insensitive substring match: a user on display name, user name or email; a group on display name or name. Counts stay totals.

cursor
string

Opaque cursor from next_cursor; returns the page after it

before
string

Opaque cursor from prev_cursor; returns the page before it (exclusive with cursor)

limit
integer

Maximum subjects to return (default 50, max 200)

Responses

Response samples

Content type
application/json
{
  • "group_grants": 0,
  • "next_cursor": "string",
  • "prev_cursor": "string",
  • "subjects": [
    ],
  • "user_grants": 0
}

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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "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",
  • "drained": true,
  • "id": "string",
  • "members": [
    ],
  • "name": "string",
  • "projected_deletion_at": "string",
  • "source": "string",
  • "source_value": "string",
  • "source_variable": "string",
  • "transitive_member_count": 0,
  • "updated_at": "string"
}

Rename a Model Set

Authorizations:
BearerAuth
path Parameters
id
required
string

Model Set UUID

header Parameters
If-Match
required
string

ETag from GET /v1/model-sets/{id}

Request Body schema: application/json
required

New name

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "string",
  • "kind": "authored",
  • "member_count": 0,
  • "model_ids": [
    ],
  • "name": "string",
  • "unrestricted": true,
  • "version": 0
}

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"
}

Replace a Model Set's membership

Authorizations:
BearerAuth
path Parameters
id
required
string

Model Set UUID

header Parameters
If-Match
required
string

ETag from GET /v1/model-sets/{id}

Request Body schema: application/json
required

Model ids, or unrestricted

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "description": "string",
  • "id": "string",
  • "kind": "authored",
  • "member_count": 0,
  • "model_ids": [
    ],
  • "name": "string",
  • "unrestricted": true,
  • "version": 0
}

Replace the Model Sets granted directly to a User

Authorizations:
BearerAuth
path Parameters
id
required
string

User UUID

header Parameters
If-Match
required
string

ETag from GET /v1/users/{id}/model-sets

Request Body schema: application/json
required

Model Set ids

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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

Replace the Model Sets granted to a UserGroup

Authorizations:
BearerAuth
path Parameters
id
required
string

UserGroup UUID

header Parameters
If-Match
required
string

ETag from GET /v1/groups/{id}/model-sets

Request Body schema: application/json
required

Model Set ids

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string",
  • "prev_cursor": "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"
}

Set a group's tool restriction on a connector

Authorizations:
BearerAuth
path Parameters
connector_id
required
string

Connector UUID

group_id
required
string

UserGroup UUID

header Parameters
If-Match
required
string

ETag from GET .../tool-restriction

Request Body schema: application/json
required

Restriction mode and tool ids

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "connector_id": "string",
  • "group_id": "string",
  • "restriction_mode": "string",
  • "tool_ids": [
    ],
  • "version": 0
}

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"
}

platform-settings

Get gateway connectivity state

Authorizations:
BearerAuth
path Parameters
gateway
required
string
Enum: "ai-gateway" "connector-gateway"

Gateway key

Responses

Response samples

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

Get the whole Platform settings

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "gateways": {
    }
}

Set gateway connectivity state

Authorizations:
BearerAuth
path Parameters
gateway
required
string
Enum: "ai-gateway" "connector-gateway"

Gateway key

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
{
  • "state": "string"
}

security

Get JWKS

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

Responses

Response samples

Content type
application/json
{ }