AI Gateway API
Table of Contents
upsquad/aigateway/v1/models_catalog.proto
AIGatewayCatalogConfig
AIGatewayCatalogConfig is the combined Get/Update payload.
| Field | Type | Label | Description |
|---|---|---|---|
| providers | Provider | repeated | Providers is the full platform provider list. |
| models | Model | repeated | Models is the full platform model list. |
| tenant_overrides | TenantOverride | repeated | TenantOverrides is the caller's tenant-scoped overrides on top of the catalog. Server-stamped; entries for other tenants are never returned. |
| updated_at | google.protobuf.Timestamp | UpdatedAt is stamped server-side on every Update. Never accepted from the client. |
GetAIGatewayCatalogConfigRequest
GetAIGatewayCatalogConfigRequest is empty — tenant id is sourced from the authenticated context.
GetAIGatewayCatalogConfigResponse
GetAIGatewayCatalogConfigResponse carries the merged catalog.
| Field | Type | Label | Description |
|---|---|---|---|
| config | AIGatewayCatalogConfig | Config is the merged catalog: platform providers + platform models + the caller's tenant overrides. Tenant overrides for other tenants are never returned. |
Model
Model is a registered model with its token budget and provider binding. Platform-global — tenant overrides live in TenantOverride.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | ID is the on-the-wire model id (e.g. "claude-opus-4-7"). | |
| provider_id | string | ProviderID is the foreign key into Provider.id. Validation rejects unknown provider ids. | |
| display_name | string | DisplayName is the human-facing label. | |
| max_input_tokens | int64 | MaxInputTokens is the compile-time context-window ceiling. 0 means "no ceiling — defer to provider". | |
| max_output_tokens | int64 | MaxOutputTokens is the per-call output ceiling (tokens). 0 means "no ceiling". |
Provider
Provider is a platform-registered LLM provider. Global — all tenants see the same list. Enabled=false hides the provider's models from the runtime router without deleting the row.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | ID is the stable identifier, lowercase dotted (e.g. "anthropic", "openai"). Immutable primary key. | |
| display_name | string | DisplayName is the human-facing label rendered in the catalog UI. | |
| enabled | bool | Enabled gates every model owned by this provider. Flipping to false is effectively a platform-wide disable. | |
| default_base_url | string | DefaultBaseURL overrides the provider SDK's hard-coded base URL when non-empty. Used for private-region routes or self-hosted compatible gateways. |
TenantOverride
TenantOverride is a per-tenant tweak on top of the platform catalog. tenant_id is server-stamped from the authenticated context — never accepted from the wire.
| Field | Type | Label | Description |
|---|---|---|---|
| model_id | string | ModelID must match a Model.id in the catalog. A row referencing a missing model is rejected at Update time. | |
| enabled | bool | Enabled hides the model from the caller's tenant when false, regardless of the platform-level Model/Provider state. | |
| rate_limit_rpm | int32 | RateLimitRPM caps requests-per-minute for this tenant on this model. 0 means "use the platform default". |
UpdateAIGatewayCatalogConfigRequest
UpdateAIGatewayCatalogConfigRequest carries the desired new catalog. L5 actors see providers + models applied; L4 actors see only tenant_overrides applied (providers / models are ignored with a server-side log line, not an error, to keep the round-trip simple).
| Field | Type | Label | Description |
|---|---|---|---|
| config | AIGatewayCatalogConfig | Config is the desired new catalog. L5 actors may mutate providers + models + tenant_overrides; L4 actors mutate tenant_overrides only (platform fields on the wire are dropped server-side). |
UpdateAIGatewayCatalogConfigResponse
UpdateAIGatewayCatalogConfigResponse echoes the merged catalog after the write.
| Field | Type | Label | Description |
|---|---|---|---|
| config | AIGatewayCatalogConfig | Config is the merged catalog after the write, same shape as Get. |
AIGatewayCatalogConfigService
AIGatewayCatalogConfigService exposes the providers / models catalog as a single Get/Update pair. LLD-4 §2.1 shape.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetAIGatewayCatalogConfig | GetAIGatewayCatalogConfigRequest | GetAIGatewayCatalogConfigResponse | Get the merged catalog (platform providers + platform models + caller's tenant overrides). Read-only, L3. |
| UpdateAIGatewayCatalogConfig | UpdateAIGatewayCatalogConfigRequest | UpdateAIGatewayCatalogConfigResponse | Update replaces the catalog for the caller's scope: - L5 actor: full catalog (providers + models + tenant overrides) - L4 actor: tenant overrides only; providers / models ignored Emits one config.updated audit event on success. |
upsquad/aigateway/v1/provider_key.proto
SetProviderKeyRequest
SetProviderKeyRequest carries the provider id + the raw secret. The tenant is taken from the auth context (never from the request body).
| Field | Type | Label | Description |
|---|---|---|---|
| provider | string | provider is the lowercase provider id, e.g. "anthropic" | |
| api_key | string | api_key is the raw provider secret. It is stored encrypted in the vault and is NEVER echoed back, logged, or persisted to any table. |
SetProviderKeyResponse
SetProviderKeyResponse confirms the write WITHOUT returning the secret.
| Field | Type | Label | Description |
|---|---|---|---|
| provider | string | provider echoes the stored provider id. | |
| key_hint | string | key_hint is a masked fingerprint (last 4 chars only), safe to render in the UI to confirm which key was stored — e.g. "••••AB12". | |
| created | bool | created is true when this was a first-time set, false when it rotated an existing key for the same (tenant, provider). | |
| updated_at | google.protobuf.Timestamp | updated_at is the server time the key was written. |
AIGatewayProviderKeyService
AIGatewayProviderKeyService is the thin tenant BYOK key-write surface. Write-only: there is deliberately no Get/List RPC — secret material never leaves the vault after it is set.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| SetProviderKey | SetProviderKeyRequest | SetProviderKeyResponse | SetProviderKey upserts the caller tenant's API key for an LLM provider. Idempotent on (org, "_default", provider): a second call rotates the key. Emits one provider_key.set audit event on success carrying only the provider + a masked hint — never the raw key. Requires L4 clearance. |
Scalar Value Types
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|---|---|---|---|---|---|---|---|
| double | double | double | float | float64 | double | float | Float | |
| float | float | float | float | float32 | float | float | Float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |