Naming and Data

Casing

Component names become type names in SDKs, MCP tool schemas and Terraform. One spelling means nobody has to remember whether a two-letter acronym is capitalized, and a name reads the same as the property it types (apiKey is an ApiKey).

Code
AiSmartRouterPolicyInput: …
ApiKeyWithSecret: …

Code
AISmartRouterPolicyInput: …
APIKeyWithSecret: …

Header components are the exception: they are named after the header they define (RetryAfter, WWWAuthenticate).

Identifiers

Resources are identified by opaque IDs, exactly as the service that owns the resource mints them. v4 never adds, renames or strips a prefix, so an ID in v4 is the same string as in the service, its logs and its database. Most carry the service's prefix (prj_, bckt_, csmr_), and some have none: accounts are UUIDs, environments and deployments are plain strings, and a built-in AI provider is its name (Anthropic). IDs are strings, and clients never parse them: the URL and the …Id property say what an ID is. People have one too: their Zuplo user ID, user_… (V4-DATA-5). AI pools, apps and user apps share gateway-service's config_ (question 1, question 33).

Code
{
  "id": "config_Kx7gDiGs…",
  "poolId": "config_IM1F8Z4r…"
}

Code
{
  "appId": 4182,
  "pool": "IM1F8Z4r…"
}

People are their user ID

The user ID is the id of the person's user record in tenant-api. Zuplo assigns it when a person is first added to an account, before they ever sign in, so a client can add them to pools and projects in the next request (question 5). The sub, the subject the identity provider assigned them (auth0|…, samlp|…), exists only after their first sign-in. Account members carry it as sub, null until then, and the members list filters by it (?sub=).

Code
{
  "userId": "user_Jm5tR8wQz2KcX7vB4nLp9HdS",
  "ownerId": "user_Hb3Wq7nTz5LcY1xK8vRm2PsF"
}

Code
{
  "userId": "user_Jm5tR8wQz2KcX7vB4nLp9HdS",
  "sub": "auth0|65f1c2d9…",
  "status": "active"
}

Code
GET /v4/buckets/{bucketId}/ai/pools/{poolId}/members/auth0%7C65f1c2d9…

Timestamps

Every timestamp is an RFC 3339 UTC string with format: date-time (DATA-1), and its name ends in On (NAME-2). It also works the other way round: a property ending in On is always a timestamp.

Code
{
  "createdOn": "2026-10-07T09:14:02.117Z",
  "expiresOn": null
}

Code
{
  "createdAt": 1759828442,
  "expiryTime": "07/10/2026 11:14"
}

Every response has the same shape

Every property of a response is always present (DATA-2). In the spec, every response property is required, and optional values are nullable (type: [string, "null"]).

Code
{
  "id": "key_XKrbtT8H…",
  "description": null,
  "expiresOn": null
}

Code
{
  "id": "key_XKrbtT8H…"
}

Responses are open: new properties may be added at any time (non-breaking), and clients ignore properties they do not know.

Everything is typed

Today's AI Gateway "configuration" stores everything in an untyped metadata JSON object. It cannot be validated, documented, or turned into MCP tools or Terraform.

Code
{
  "policies": [
    {
      "type": "model-override",
      "enabled": true,
      "completions": { "default": "openai1/gpt-4o-mini", "force": null },
      "embeddings": null
    },
    {
      "type": "metering",
      "enabled": true,
      "budgetRules": [{ "budgetBy": "app", … }],
      "failOnError": false
    }
  ]
}

Code
{
  "metadata": {
    "inboundPolicyChain": [
      {
        "name": "ai-gateway-metering-inbound",
        "options": { … }
      }
    ]
  }
}

Code
deploymentModels:
  type: [object, "null"]
  maxProperties: 100
  additionalProperties:
    type: string
    maxLength: 255

Code
metadata:
  type: object
  additionalProperties: true

Requests and responses are different schemas

Request schemas never contain server-owned fields (id, createdOn), so SDK method signatures and MCP tool input schemas only ever show what a client can actually send. This is stricter than ROB-4, which allows a single schema with readOnly/writeOnly markers.

Scalar components such as enums (ProviderType) are shared by both.

Code
CreateAiAppRequest:
  type: object
  additionalProperties: false
  required: [name]
  properties:
    name: { type: string, maxLength: 128 }

Code
AiApp:
  type: object
  properties:
    id: { type: string, readOnly: true }
    name: { type: string }

Secrets

A person's consumer is theirs, and a user app admin can create it for them. The admin sees the first key's secret once, in the response, and the person reads it when they need it. Only the keys of personal consumers have this singleton: the keys of an app's or the bucket's consumers are seen once, by whoever creates them.

Money, units and durations

Code
{ "inputPerMillionTokens": 0.15 }

Code
{ "inputPerToken": 0.00000015 }

Code
{ "fallbackTimeoutSeconds": 30 }

Code
{ "fallbackTimeout": 30000 }

The property name or description states the unit ("value is in US dollars for cost"). If a schema ever needs another currency, it gets an explicit currency field.

Booleans

Code
{ "inheritPolicyTemplate": true }

Code
{ "noInheritance": false }

The default is the safe or common case.