Management API reference

Administrative control plane: keys, users, orgs, budgets, guardrails, credentials, compliance. Requires an attested administrator identity — see Authentication & Scoping.

Generated from the OpenAPI specification. A continuous-integration check enforces the specification against the running router in both directions — an undocumented route fails the build, and so does a documented route that no longer exists. This reference therefore cannot silently drift from the implementation.

122 operations across 21 groups.

A note on free-form responses

Some operations document their body as a free-form object (additionalProperties: true). That is deliberate, not an omission, and it means one of two things:

• Provider passthrough. The gateway forwards the upstream provider’s payload verbatim. Restating the provider’s schema here would create a second source of truth that drifts from theirs. Use the provider’s own documentation for those shapes.
• Application-defined JSON. The value comes from a JSONB column the application does not structurally constrain.

Where a shape is pinned, this reference names the schema and lists its fields. So ChatCompletionRequest — model*: string, … is a contract; “free-form object” is an honest admission that it is not.

Contents

• key — 8 operations
• user — 5 operations
• team — 9 operations
• organization — 8 operations
• customer — 4 operations
• budget — 5 operations
• model — 5 operations
• credential — 6 operations
• guardrail — 7 operations
• callback — 3 operations
• config — 2 operations
• dataset — 4 operations
• developer — 9 operations
• eval_job — 4 operations
• eval_suite — 2 operations
• openapi — 1 operations
• pipeline — 12 operations
• schema — 1 operations
• tag — 4 operations
• tier — 1 operations
• v1 — 22 operations

key

POST /key/block

Soft-block a key (blocked keys 401 on /v1/* but remain queryable)

Request body (required): key: string, key_id: string

POST /key/delete

Delete one or more API keys

Request body (required): key: string, key_id: string, keys: array, key_aliases: array

POST /key/generate

Generate a new API key

Request body (required): key_name: string, key_alias: string, user_id: string, team_id: string, max_budget: number|null, models: array, rpm_limit: integer|null, tpm_limit: integer|null … +3

GET /key/info

Look up a single API key by token or id

GET /key/list

List API keys

POST /key/unblock

Reverse a soft-block on a key

Request body (required): key: string, key_id: string

POST /key/update

Update an existing API key

Request body (required): key*: string, key_name: string, key_alias: string, max_budget: number|null, models: array, rpm_limit: integer|null, tpm_limit: integer|null, expires: string|null … +2

POST /key/{key}/regenerate

Regenerate (rotate) a key’s token in place

user

POST /user/delete

Delete a user (soft-delete; spend history preserved)

Request body (required): user_id*: string

GET /user/info

Get a single user by id or email

GET /user/list

List users

POST /user/new

Create a new user

Request body (required): user_email: string, user_role: string, name*: string

POST /user/update

Update a user’s role or profile

Request body (required): user_id*: string, user_role: string|null

team

POST /team/block

Soft-block a team

Request body (required): team_id*: string

POST /team/delete

Delete a team

Request body (required): team_id*: string

GET /team/info

Get a single team

41-13: response enriched additively (id, alias, name, org_id, org_name, member_count, max_budget, total_spend, current_spend, status, created_at) alongside team_id/team_alias/spend.

GET /team/list

List teams

41-13: rows enriched additively (see /team/info) alongside the pre-existing team_id/team_alias/spend/blocked.

POST /team/member_add

Add a user to a team

Request body (required): team_id: string, user_id: string, role: string

POST /team/member_delete

Remove a user from a team

Request body (required): team_id: string, user_id: string

POST /team/new

Create a team

Request body (required): team_alias*: string, organization_id: string, max_budget: number|null, rpm_limit: integer|null, tpm_limit: integer|null, models: array

POST /team/unblock

Reverse a soft-block on a team

Request body (required): team_id*: string

POST /team/update

Update a team

Request body (required): team_id*: string, team_alias: string, max_budget: number|null

organization

POST /management/organizations/{id}/apply_tier

Apply a tier’s resolved limits to an organization (idempotent)

Resolves the tier (by external_id) from the plan_tiers catalog, merges any per-subscription override, and applies the effective limits to the organization’s budget/api-key rows idempotently. NULL-soft: an unsynced external_id applies the override only and never zeroes an existing budget. Control-plane principals only (tenant principal → 403). Org id comes from the path; any body id is inert.

Request body (required): external_id*: string, override: object

POST /organization/delete

Delete an organization

Request body (required): organization_id*: string

GET /organization/info

Get a single organization

41-13: response enriched additively (alias, name, metadata, member_count, team_count, total_spend, created_at) alongside id/organization_alias/spend.

GET /organization/list

List organizations

41-13: rows enriched additively (alias, name, member_count, team_count, total_spend, created_at) alongside id/organization_alias/spend.

POST /organization/member_add

Add a user to an organization

Request body (required): organization_id: string, user_id: string, role: string

POST /organization/member_delete

Remove a user from an organization

Request body (required): organization_id: string, user_id: string

POST /organization/new

Create an organization

Request body (required): organization_alias*: string, max_budget: number|null, models: array

POST /organization/update

Update an organization

41-13: this route now performs a REAL scoped UPDATE (it was a no-op that only audited intent). organization_alias + metadata are persisted via COALESCE (omitted field = column untouched), behind the unchanged own-org gateOrgWriteScope gate.

Request body (required): organization_id*: string, organization_alias: string, metadata: object, max_budget: number|null

customer

POST /customer/delete

Delete a customer

Request body (required): customer_id*: string, id: string, end_user_id: string

GET /customer/list

List customers

41-15: rows enriched additively (external_user_id + alias — dashboard-parity duplicates of the spec-locked end_user_id / end_user_name, which keep their exact names and derivations — plus default_model, allowed_model_region) alongside the pre-existing id/spend/blocked/created_at.

POST /customer/new

Create a customer

Request body (required): user_id*: string, alias: string, max_budget: number|null, models: array, end_user_id: string, end_user_name: string

POST /customer/update

Update a customer

41-15: the handler targets by the additive id (row UUID) or by the historical end_user_id (external user id) — both through the same scope gate. end_user_name/blocked persist via COALESCE.

Request body (required): customer_id*: string, max_budget: number|null, id: string, end_user_id: string, end_user_name: string, blocked: boolean

budget

POST /budget/delete

Delete a budget tier

Request body (required): budget_id*: string

GET /budget/info

Get a single budget tier

GET /budget/list

List budget tiers

41-14: rows enriched additively (name — blank rendered as “unnamed”, duration + budget_duration, soft_budget, rpm_limit, tpm_limit, reset_at, created_at, current_spend) alongside the pre-existing id/max_budget.

POST /budget/new

Create a budget tier

41-14: request gains name + soft_budget (additive); budget_duration/rpm_limit/tpm_limit are now persisted (previously accepted but dropped).

Request body (required): budget_id*: string, max_budget: number, budget_duration: string, tpm_limit: integer|null, rpm_limit: integer|null, name: string, soft_budget: number|null

POST /budget/update

Update a budget tier

41-14: this route now performs a REAL scoped UPDATE (it was a no-op that only audited intent) — COALESCE semantics, so an omitted field leaves the column untouched. Response shape unchanged.

Request body (required): budget_id*: string, max_budget: number, budget_duration: string, name: string, soft_budget: number|null, rpm_limit: integer|null, tpm_limit: integer|null

model

POST /model/delete

Remove a model from the registry

Request body (required): model_id*: string

GET /model/info

Get a registered model

41-16: response enriched additively (id, name, created_at) alongside the pre-existing model_name/model_info/aosentry_params. Reads stay open to all admin tiers (global fleet catalog).

GET /model/list

List registered models

41-16: rows enriched additively (id, name, provider, health, response_time_ms, last_checked_at, lifecycle, is_self_hosted, created_at — dashboard-parity health/lifecycle join fields) alongside the pre-existing model_name/model_info. Reads stay open to all admin tiers and unfiltered (global fleet catalog); writes remain Instance-only (41-08).

POST /model/new

Add a model to the registry

Request body (required): model_name*: string, litellm_params: object, model_info: object

POST /model/update

Update a model registry entry

Request body (required): model_id*: string, model_name: string, litellm_params: object

credential

POST /credential/delete

Delete a stored credential

41-16: gains additive id (row UUID) targeting, dual-keyed with the handler’s historical credential_name arm.

Request body (required): credential_id*: string, id: string, credential_name: string

GET /credential/list

List stored credentials (credential_info string values are redacted)

41-16: rows enriched additively (id, created_by, created_at, updated_at) alongside the pre-existing credential_name/credential_info; credential_info masking tightened from api_key-only to ALL string values (admin-family parity — deliberate security tightening, field names unchanged). Instance-only, like every /credential/* verb (41-08).

POST /credential/new

Store a provider credential

Request body (required): credential_name: string, credential_info: object

GET /credential/provider-presets

List known provider defaults for the “Add Credential” form

Returns the provider preset catalog (name, api_base, custom_llm_provider, api_key_header) with detected stamped per entry — whether a matching key is present in the gateway’s environment. NEVER returns key material; only the boolean. Instance-only, like every /credential/* verb.

POST /credential/provision-from-env

Create a provider credential from a key already in the gateway env

Reads the provider’s key from the gateway’s OWN environment, stores it as a credential and fires the autopopulate sync — the raw key never reaches the browser. DEV-ONLY: returns 404 when Environment=production, because production credentials come from the secret store. Instance-only.

Request body (required): provider*: string

POST /credential/update

Update a stored credential

41-16: gains additive id (row UUID) targeting, dual-keyed with the handler’s historical credential_name arm — only the id arm can rename (credential_name becomes a write value); unknown id → 404. All /credential/* verbs are Instance-only (41-08).

Request body (required): credential_id*: string, id: string, credential_name: string, credential_values: string, credential_info: object

guardrail

POST /guardrail/check

Evaluate a guardrail against an input payload (dry-run)

Request body (required): guardrail_id: string, input: string

POST /guardrail/delete

Delete a guardrail

Request body (required): guardrail_id*: string

GET /guardrail/list

List guardrails

41-14: rows enriched additively (name — duplicate of guardrail_name for parsers keyed on name, aosentry_params, guardrail_info) alongside the pre-existing id/guardrail_name/guardrail_type/enabled/created_at.

GET /guardrail/logs

List guardrail evaluation logs

41-14: rows enriched additively (confidence, stage — execution_stage with “pre” default, original_content, modified_content, created_at) alongside the pre-existing id/request_id/guardrail_name/status/duration_ms; status stays the raw column.

GET /guardrail/logs/stats

Aggregated guardrail-log statistics

POST /guardrail/new

Create a guardrail

41-14: an empty guardrail_type is inferred from the name / aosentry_params shape (admin-family inferGuardrailType parity); an operator-supplied type passes through unchanged.

Request body (required): guardrail_name: string, guardrail_type: string, mode*: string, config: object

POST /guardrail/update

Update a guardrail

41-14 (docs catch-up): guardrail_name / guardrail_type / aosentry_params / enabled were already accepted and persisted by the handler; documented here because the dashboard’s enable/disable toggle converges onto {guardrail_id, enabled}. Writes are scope-gated (foreign-org / NULL-org targets → 403).

Request body (required): guardrail_id*: string, mode: string, config: object, guardrail_name: string, guardrail_type: string, aosentry_params: object, enabled: boolean

callback

POST /callback/delete

Remove a registered callback

Request body (required): callback_id*: string

GET /callback/list

List registered callbacks

POST /callback/new

Register a webhook callback

Request body (required): url: string, events: array, secret: string

config

GET /config/list

List runtime config entries

POST /config/update

Update one or more runtime config entries

Request body (required): object

dataset

GET /management/dataset/list

List datasets

Lists every dataset asset in the attested tenant’s namespace. Tenant isolation is structural — the namespace path IS the boundary (SC6).

POST /management/dataset/new

Create a dataset

Validates the content against the dataset JSON Schema (C-02; required name/storage_format/table_ref) and persists it as a catalog asset (asset_type=‘dataset’) in the attested tenant’s namespace. table_ref.snapshot_ids carries the Iceberg reproducibility pin (SC2).

Request body (required): name: string, content: object

POST /management/dataset/{id}/items

Append items to a dataset

Appends jsonl-style test-case items into the dataset asset’s provenance.items array and re-validates the merged content against the dataset schema before persisting via AIAssetStore.Update (which bumps the version + content-hash atomically).

Request body (required): items*: array

POST /management/dataset/{id}/sample_from_production

Sample production traffic into a dataset

Reads a bounded, tenant-filtered sample of production spend_logs rows (metadata.tenant_id = the attested tenant) and appends them as dataset items. sample_size is capped server-side; the tenant binding is the attested principal exclusively (no tenant_id wire field), so a cross-tenant sample is structurally impossible.

Request body (required): sample_size*: integer

developer

GET /developer/v1/audit

Audit entries involving the calling developer

Returns audit_logs rows where either the developer was the actor (changed_by = ‘api-key:_{’ — the attested actor string) OR the resource is one of the developer’s api_keys (table_name=‘api_keys’ AND object_id IN developer’s keys by aoid_credential_id). Newest first. Cross-developer leak is prevented by the IN subquery restricting object_id to keys owned by the calling developer.}

GET /developer/v1/keys

List the developer’s own active keys

Returns the calling developer’s active (non-discarded) API keys. The raw token column is NEVER included — only the id and public metadata. Pagination via standard limit/offset query params.

POST /developer/v1/keys

Mint a self-service API key

Create a new API key bound to the calling developer’s attested credential (aoid_credential_id). Security invariants enforced server-side:

1. aoid_credential_id is sourced from the attested context (request-body user_id / team_id / organization_id are dropped — never trusted).
2. team_id and organization_id are zeroed.
3. max_budget is clamped to (developer ceiling - allocated). Exceeding the remaining grant returns 400.
4. models[] defaults to the developer’s own allowlist when omitted (NEVER empty for a restricted developer, because empty in api_keys = “all models” — bypass key blocked).
5. models[] is intersected with the developer’s allowlist — a developer cannot grant a model outside their own grant set. Per-developer key cap (default 10, override via env DEVELOPER_MAX_KEYS_PER_USER) enforced before INSERT.

Audit row recorded with changed_by=“api-key:_{” via the attested actor string.}

Request body (required): key_name: string, key_alias: string, max_budget: number|null, models: array, rpm_limit: integer|null, tpm_limit: integer|null, expires: string|null

DELETE /developer/v1/keys/{id}

Revoke one of the developer’s keys (soft-delete)

Sets discarded_at = now() on the key. Same ownership filter as GET: 404 (not 403) is returned for foreign or non-existent keys. Audit row recorded with changed_by=“developer:”.

GET /developer/v1/keys/{id}

Retrieve one of the developer’s keys

Returns the key’s public metadata. 404 is returned BOTH when the key genuinely does not exist AND when it exists but is not owned by the calling developer — distinguishing the two would leak key existence (RESEARCH Pitfall: no enumeration via 403-vs- 404 split). The raw token is never included in the response.

GET /developer/v1/models/available

List models the developer can grant on minted keys

Returns the proxy_models registry INTERSECTED with the developer’s users.models[] allowlist. When the developer is unrestricted (users.models[] is empty), the full registry is returned. When restricted, only models in the developer’s grant set appear — out-of-allowlist models are SILENTLY ABSENT (no error, no enumeration leak).

This endpoint preserves the 404-on-unauthorized-model property (SC2) for the developer surface: a model NOT in the developer’s grant set is not discoverable through this list endpoint.

GET /developer/v1/spend

Total spend + request count for the calling developer’s keys

Returns the calling developer’s total_spend + total_requests over the date window. Scoped by aoid_credential_id (the attested self-scope derived from the AOID-signed context). A developer NEVER sees another developer’s totals. Discarded keys’ historic spend IS included (the developer spent that money; the key was just revoked afterward).

GET /developer/v1/spend/logs

Paginated spend_logs for the calling developer’s keys

Returns spend_logs rows for keys owned by the calling developer, ordered by start_time DESC (newest first). page is 0-indexed.

GET /developer/v1/usage

Per-key spend breakdown for the calling developer

Returns one row per api_key owned by the calling developer with request count + spend in the window. Sorted by spend DESC. Empty key aliases are preserved as-is — the portal handles display.

eval_job

GET /management/eval_job/list

List eval jobs (tenant-scoped)

Returns a paginated list of eval_jobs rows for the caller’s tenant, ordered newest-first (created_at DESC). Enforces the tenant isolation matrix from Obj 16 TRD 16-10 (mirrors ListRuns):

• Plain tenant admin: sees only own-tenant rows. ?tenant= → 403.
• master_key class OR cross_tenant_admin entitlement: may pass ?tenant= override (audited as eval_job.tenant_override).

aggregate_score and verdict are omitted when no eval_results exist yet for a job (no fake zeros). For per-job scores and verdict use GET /management/eval_job/{id}/results.

POST /management/eval_job/new

Launch an eval pipeline run

Opens ONE pgx.Tx, INSERTs pipeline_runs + eval_jobs in the same tx, emits the pipeline.run.start provenance entry (A-04 outbox), and ExecuteWorkflow’s EvalRunWorkflow on TaskQueueEval with EVERY reproducibility input PINNED at run start (SC2): the suite version defaults to the catalog head when omitted, temperature is pinned to 0, and the reproducibility seed flows through unchanged. A Temporal failure rolls the whole tx back — no orphan run row. The tenant comes from the attested principal exclusively (SC6); there is no tenant_id wire field.

Request body (required): eval_suite_id*: string, eval_suite_version: integer, model_asset_id: string, model_version: string, judge_model_version: string, dataset_snapshot_ids: array, reproducibility_seed: integer

GET /management/eval_job/{id}

Get one eval job

Reads eval_jobs + pipeline_runs from Postgres (never Temporal visibility — anti-pattern). The wrong-tenant gate (SC6) 404s a job owned by a different tenant — never leaks its existence.

GET /management/eval_job/{id}/results

Get eval-job scores + verdict

Returns the eval_scores rows + the latest eval_results verdict bound to THIS job (job_id guard). A missing verdict on a still-running job is NOT an error — the verdict field is simply absent. Same wrong-tenant gate (SC6) as GET /eval_job/{id}.

eval_suite

POST /management/eval_suite/new

Create an eval suite

Validates the content against the eval_suite JSON Schema (C-02; required name/eval_type/test_cases) and persists it as a catalog asset (asset_type=‘eval_suite’) in the attested tenant’s namespace. Versioning + content-hash come from the catalog store. Returns the catalog asset_id and the just-assigned version.

Request body (required): name: string, content: object

GET /management/eval_suite/{id}/versions

List eval suite versions

Surfaces the append-only version history for an eval_suite asset from the shipped AIAssetVersionStore. A job pins a specific suite version (SC2) by reading from here.

openapi

GET /openapi/{filename}

Serve an embedded OpenAPI YAML file

Returns the bytes of one of the embedded OpenAPI YAML files (management.yaml, _components.yaml; v1.yaml after TRD 02). Public route — no authentication required. The contract has no secrets in it.

pipeline

GET /management/pipelines/definitions

List pipeline definitions

POST /management/pipelines/definitions

Register a pipeline definition

Compiles the DSL via dsl.Compile, validates the content against the pipeline_definition JSON Schema (C-02; 13-value operator enum), and persists as a catalog asset under (aocore, pipelines). Returns the catalog asset_id, the just-assigned version, and the Temporal workflow type name (pipeline_<assetID-first-8>_v<version>).

Request body (required): name: string, dsl_source: string

GET /management/pipelines/definitions/{id}

Get one pipeline definition

GET /management/pipelines/hitl/pending

List pending human-in-the-loop reviews

Returns the pipeline_runs rows in status=‘awaiting_review’ scoped to the caller’s tenant — the HITL reviewer inbox (G-07). Cross-tenant via ?tenant=other is master-key/admin-only and audit-logged; non-admin callers receive 403 forbidden.

The reviewer-role filter is a documented C-04 RBAC stub: every authenticated caller currently sees ALL pending reviews for the (effective) tenant. step_id / step_name / reviewer_role project as empty strings until the parked-step descriptor lands with C-04.

GET /management/pipelines/runs

List pipeline runs

Returns pipeline_runs rows filtered to the caller’s tenant (per attested context). Cross-tenant via ?tenant=other is master-key/admin-only and audit-logged; non-admin callers receive 403 forbidden.

POST /management/pipelines/runs

Start a pipeline run

Resolves the Temporal namespace + task queue from the attested principal via temporal.ResolveNamespace. Opens a pgx.Tx, INSERTs the pipeline_runs row, emits the pipeline.run.start audit chain entry (F-01 wire format) IN THE SAME tx, calls temporal.Client.ExecuteWorkflow, and commits. Wrong-tenant smuggling is structurally impossible — the request body has no tenant_id field.

Request body (required): definition_id*: string, definition_version: string, initial_inputs: object

GET /management/pipelines/runs/{id}

Get one pipeline run

POST /management/pipelines/runs/{id}/cancel

Cancel a pipeline run (graceful)

Sends Temporal CancelWorkflow. Activities observe workflow.IsCanceled and clean up; subsequent activities are not scheduled. Compare with /terminate which is destructive.

GET /management/pipelines/runs/{id}/history

Paginated Temporal workflow history events

G-12 replaces the G-04 stub with real paginated Temporal history. Returns events in the Flutter wire shape consumed by G-05 EventHistoryView and G-06 projectStepsFromHistory. Pagination is offset-based: ?limit (default 100, max 1000) + ?next_page_token (opaque stringified offset). Final page omits next_page_token. When Temporal is not configured, returns 503 temporal_not_configured.

POST /management/pipelines/runs/{id}/signal

Send a signal to a pipeline run

Forwards a Temporal signal (e.g. human_review_decision with payload {approved: bool, reason: string} for the human_review operator).

Request body (required): signal_name*: string, payload: object

GET /management/pipelines/runs/{id}/stream

SSE live updates for a pipeline run

Server-Sent Events stream. Polls Temporal every 2 seconds and emits one of three event types: state-change (status transition), heartbeat (no change), terminal (final status; stream closes). Latency budget: 2.3s p99 from state change to client render (G-RESEARCH Domain 5).

POST /management/pipelines/runs/{id}/terminate

Terminate a pipeline run (destructive)

Sends Temporal TerminateWorkflow. Activities are NOT given a graceful shutdown signal; the workflow halts immediately. Use /cancel for graceful shutdown.

Request body (optional): reason: string

schema

GET /management/schema

Return the management API JSON schema descriptor

Self-describing endpoint that returns a machine-readable summary of the management API surface. Independent of the OpenAPI spec served at /openapi/management.yaml — see go/internal/api/management/schema.go.

tag

POST /tag/delete

Delete a tag

Request body (required): tag_id*: string, id: string, name: string

GET /tag/list

List tags

41-15: rows enriched additively (id — the UI row identity and update/delete mutation key) alongside the pre-existing name/color/description.

POST /tag/new

Create a tag

Request body (required): tag_name*: string, description: string, name: string, color: string

POST /tag/update

Update a tag

41-15: promoted from a recorded no-op to a REAL scoped UPDATE. The handler targets by the additive id (row UUID — required for rename, which cannot address the row it renames by name) or by the unique name; name/color/description persist via COALESCE (omit to leave unchanged). Both arms ride the same scope gate.

Request body (required): tag_id*: string, tag_name: string, description: string, id: string, name: string, color: string

tier

POST /management/tiers

Upsert a plan-tier catalog row (control-plane sync target)

Idempotent upsert of a tier into the global plan_tiers catalog, matched on external_id (= eden-biz plan_key). First push inserts (201); re-push updates in place (200). Control-plane principals only; a tenant principal is rejected (403).

Request body (required): external_id*: string, slug: string, max_budget: number|null, soft_budget: number|null, rpm_limit: integer|null, tpm_limit: integer|null, models: array

v1

POST /management/v1/agent/chat

Attested chat completion (agent LLM step)

OpenAI-compatible chat+tools completion authenticated by the ATTESTED Principal (no API key). Mounted under AttestedAdminMiddleware. Accepts the OpenAI chat shape (messages + tools) and reuses the same LLM proxy as /v1/chat/completions: resolves model→provider→credential, runs guardrails, calls the upstream provider, and returns the assistant message + tool_calls + usage. Used by the agent loop worker so the LLM step runs as the attested operator identity rather than a service API key. Streaming is not supported on this path.

Request body (required): model: string, messages: array, tools: array, tool_choice: any

GET /management/v1/billing-export/usage

Versioned cursor-paginated billing-data export (v1 pull seam)

Stable versioned pull API serving daily per-org usage/spend aggregates to EXTERNAL billing systems. AOCore produces billing-usable data; external systems price and invoice (locked decision 3).

CONTRACT STABILITY RULES (see docs/billing/billing-export-seam.md):

• version field is always “v1”; v2 would use /billing-export/v2/usage.
• Records for a closed UTC day are immutable (aggregate over spend_logs).
• Field evolution is additive-only: new fields may appear; existing fields are never removed or renamed without a path-level version bump.
• Cursor is opaque (base64 of internal position); callers must NOT parse or construct cursor values.
• Complete-or-loud: any tenant schema error returns 500 naming the tenant (billing data must be complete or explicitly broken — never silently partial, unlike orgs/usage).
• v1 is PULL (stateless, replayable, external biller controls cadence). Push (scheduled exporter/webhook) is the designed additive extension (see seam doc); it is NOT built in v1.

Ordering: (period_start ASC, org ASC) — deterministic and stable. Auth: AttestedAdminMiddleware.

DELETE /management/v1/catalog/tags

Clear a catalog tag

Request body (required): ns: string, key: string, target*: object

GET /management/v1/catalog/tags

List catalog tags

POST /management/v1/catalog/tags

Apply a catalog tag

Request body (required): ns: string, key: string, value: string, target: object

GET /management/v1/catalog/vector-tables

List vector tables

Paginated, ACL-filtered list of vector tables.

GET /management/v1/catalog/vector-tables/{id}

Get vector table detail

Full vector table detail including schema + vector columns. ACL-enforced.

GET /management/v1/catalog/vector-tables/{id}/index-status/{jobId}

Poll vector index rebuild status

POST /management/v1/catalog/vector-tables/{id}/rebuild-index/{column}

Rebuild a vector column index

Triggers an async IVF_HNSW_SQ index rebuild for the column. Returns a job id.

GET /management/v1/groups/

List all groups

POST /management/v1/groups/

Create a group

Creates a new group (catalog_principal_roles row) plus a dedicated companion catalog role so per-group permissions can be granted. A name collision returns 409.

Request body (required): name*: string, catalog: string

DELETE /management/v1/groups/{id}

Delete a group

GET /management/v1/groups/{id}

Get a group by id

GET /management/v1/groups/{id}/members

List a group’s members

POST /management/v1/groups/{id}/members

Add a member to a group

Request body (required): principal_id*: string

POST /management/v1/groups/{id}/members/remove

Remove a member from a group

Request body (required): principal_id*: string

POST /management/v1/groups/{id}/permissions

Grant a permission to a group

Grants an AssetPrivilege to the group (applied to the group’s catalog role). object_type/object_id/tenant default to ai_asset / “” / “”.

Request body (required): privilege*: string, object_type: string, object_id: string, tenant: string

POST /management/v1/groups/{id}/permissions/remove

Revoke a permission from a group

Request body (required): privilege*: string, object_type: string, object_id: string, tenant: string

GET /management/v1/orgs/usage

Per-org usage aggregates (quota dashboard data source)

Returns per-org (tenant-slug) request/token/spend aggregates over a rolling time window. Fans out over all tenant schemas + public via ForEachTenantSchema. Continue-on-error: one broken tenant schema does NOT 500 the response — instead “partial”: true is set and the broken schema is skipped. This is the data source for the TRD 7-08 Flutter quota dashboard.

Wire contract (frozen — 7-08 codes against this verbatim):

• window accepts 7d|30d|90d, default 30d.
• orgs sorted ascending by slug.
• org="" rows (public/legacy scope) included only when non-zero AND tenant mode is active.
• partial=true signals at least one tenant schema was unavailable.

Auth: AttestedAdminMiddleware (attested admin identity required). No billing semantics — raw usage + recorded spend_usd from spend_logs.

GET /management/v1/tenants

List provisioned tenant slugs

Returns the sorted list of tenant slugs this instance is provisioned for (cfg.TenantSlugs / AOCORE_TENANT_SLUGS, Obj 18 TRD 18-04 contract). When no slugs are configured (multi-tenancy dormant) returns an empty array with dormant=true. Internal multi-org framing only — no reseller or downstream-tenant concepts (7-CONTEXT.md locked decisions 1-2). Consumed by the admin shell org switcher (7-10). Supersedes the G-07 NamespaceSwitcher hardcoded stub as the real tenant-discovery source.

POST /management/v1/trino/query

Execute a READ-ONLY Trino query

Runs a SELECT-class statement against Trino and returns columns + rows. READ-ONLY enforced server-side (LOCKED decision 5): any non-SELECT statement (INSERT/UPDATE/DELETE/MERGE/CREATE/DROP/ALTER/TRUNCATE/GRANT/ SET/CALL, multi-statement, or EXPLAIN ANALYZE of a write) is rejected with 403 and error.code trino_read_only BEFORE reaching Trino — defense in depth above the UI gate. Writes belong in pipelines where they carry provenance. Per-identity rate-limited; results capped (413 with Retry-With-Pagination on overflow). Returns 503 when Trino is not configured.

Request body (required): sql*: string, args: array

GET /management/v1/trino/query/history

List the caller’s read-only query history

Returns the calling identity’s own Trino workbench query history (Objective 7 TRD 7-01), newest first, capped at 100 rows. Scope is implicit and unforgeable: the actor is taken from the resolved attested principal, never from a query parameter, so no cross-actor access path exists. Reads Postgres (not Trino), so it functions even when the Trino coordinator is unconfigured.