GET and PUT /v1/admin/keys/{key_id}/caps

Part of the API reference; this page is generated from the OpenAPI document that the gateway builds from its own route tables.

Provenance

• Contract version: 1.10.0
• Contract title: acumen gateway API
• Source: acumen:docs/openapi/acumen-v1.openapi.json

Operations

GET /v1/admin/keys/{key_id}/caps

Read a virtual key’s budget caps

The configured money caps of one active virtual key: daily and monthly spend in micro-USD, and the per-minute request/token caps. A zero cap is unbounded. Operator (ops:read) scope.

• Operation id: getV1AdminKeysKeyIdCaps
• Scope: ops:read
• Exposure: operator
• Mutating: no
• Auth: bearerAuth, operatorSession

Responses

• 200: OK
  • application/json: KeyCaps: KeyCaps (object)
• 400: schema_invalid — the request body or parameter failed validation
  • application/problem+json: Problem: Problem (object)
• 401: auth_missing — no virtual key or operator session
  • application/problem+json: Problem: Problem (object)
• 403: auth_scope — the credential lacks the route’s scope
  • application/problem+json: Problem: Problem (object)
• 404: resource_not_found — the addressed object does not exist
  • application/problem+json: Problem: Problem (object)
• 405: method_not_allowed — the path exists for another verb
  • application/problem+json: Problem: Problem (object)
• 429: rate_limited — the per-key or per-IP bucket is exhausted
  • application/problem+json: Problem: Problem (object)
• 500: internal — the store or process failed
  • application/problem+json: Problem: Problem (object)
• 501: not_implemented — the route is declared but not wired in this build
  • application/problem+json: Problem: Problem (object)
• 503: store_unavailable — the dependency is down; retryable
  • application/problem+json: Problem: Problem (object)

PUT /v1/admin/keys/{key_id}/caps

Write a virtual key’s budget caps

Sets the money caps the gateway enforces on one virtual key. Every field is optional: a missing field keeps the stored value, a zero lifts the cap. The write is validated first (negative values are 400), then a hot reload is requested so the new caps are enforced without a restart. Operator (admin) scope.

• Operation id: putV1AdminKeysKeyIdCaps
• Scope: admin
• Exposure: operator
• Mutating: yes
• Auth: bearerAuth, operatorSession

Request

• Request body (application/json, required): KeyCapsPatch: KeyCapsPatch (object)

Field	Type	Required	Notes
daily_usd	number	no
monthly_usd	number	no
rpm	integer	no
tpm	integer	no

Responses

• 200: the caps now in force
  • application/json: KeyCaps: KeyCaps (object)
• 400: schema_invalid — the request body or parameter failed validation
  • application/problem+json: Problem: Problem (object)
• 401: auth_missing — no virtual key or operator session
  • application/problem+json: Problem: Problem (object)
• 403: auth_scope — the credential lacks the route’s scope
  • application/problem+json: Problem: Problem (object)
• 404: unknown or inactive virtual key
  • application/problem+json: Problem: Problem (object)
• 405: method_not_allowed — the path exists for another verb
  • application/problem+json: Problem: Problem (object)
• 429: rate_limited — the per-key or per-IP bucket is exhausted
  • application/problem+json: Problem: Problem (object)
• 500: internal — the store or process failed
  • application/problem+json: Problem: Problem (object)
• 501: not_implemented — the route is declared but not wired in this build
  • application/problem+json: Problem: Problem (object)
• 503: store_unavailable — the dependency is down; retryable
  • application/problem+json: Problem: Problem (object)