Lists, Pagination and Filters

Every list paginates

That includes collections that are small today (a gateway's user apps, a pool's members). The shared guidelines exempt "bounded" collections. v4 does not: adding pagination later is a breaking change (VER-3), and one shape means one code path in every client, SDK and MCP tool.

Code
{
  "data": [{ "id": "config_IM1F…", "name": "Engineering" }],
  "limit": 2,
  "offset": 2,
  "total": 3,
  "hasMore": false,
  "next": null
}

Code
[
  { "id": "config_IM1F…", "name": "Engineering" },
  { "id": "config_9xQa…", "name": "Support" }
]

Code
GET /v4/buckets/bckt_Y40ypGODCDP3S7iZxNwCAbIe/ai/pools?limit=2&offset=2

This is the shared envelope (COLL-2) exactly. In the spec it is a component named {Resource}List (AiPoolList) with exactly these six properties, all required.

Order

Every list has one stable, documented order, stated in the operation description. Ties are broken by ID, so pages never overlap or skip items while the collection is unchanged.

Filters

A filter is a query parameter named after the field it filters, in camelCase, and it matches exactly.

Code
GET /v4/buckets/{bucketId}/ai/pools?parentPoolId=config_IM1F…

Code
GET /v4/accounts/{accountId}/buckets?environmentType=production

Code
GET /v4/buckets/{bucketId}/[email protected]

Code
GET /v4/buckets/{bucketId}/ai/pools?filter=parent:config_IM1F…

Code
GET /v4/accounts/{accountId}/buckets?filter[environmentType]=production

Code
GET /v4/buckets/{bucketId}/ai/pools?parentPoolId=…

Code
GET /v4/buckets/{bucketId}/ai/pools/{poolId}/pools

See the owner is a property.

Code
GET /v4/buckets/{bucketId}/ai/user-apps/{userAppId}/users/user_Jm5tR8wQ…/consumers

Code
GET /v4/buckets/{bucketId}/ai/user-apps/{userAppId}/users/me/consumers

Reserved parameters

These names are reserved across v4 and mean the same everywhere. Their synonyms are rejected by lint.

Lint also rejects fields: every response always has every property.

Every other collection uses limit and offset (decided on 2026-11-05, question 10). When v4 gets its first append-only collection (build logs, request logs, audit events), it uses an opaque cursor with the same envelope minus offset and total (COLL-3), and v4-list-envelope gets that variant in the same pull request. A collection's pagination is chosen when it is introduced and never switched.

Including more with include[]

A new flag for every extra means a new parameter for every client, SDK and MCP tool to learn. include[] is one parameter that works the same everywhere, as Stripe's include[] does. A value is the property's name (consumers, apiKey), and the property's description says when it is not null.

On a create, asking for something the new resource does not have yet creates it: include[]=apiKey issues the consumer's first key. The body stays the new resource alone (bodies).

Related resources are otherwise a filtered list (/v4/buckets/{bucketId}/ai/apps?poolId=…), or for credentials a nested one (…/users/{userId}/consumers), and references are …Id fields. Data that is only ever read and changed together with its owner is part of the owner's body, not a sub-collection: a provider assignment's models are its models array, written in the same PATCH. A provider's own models are the exception, a read-only list at …/ai/providers/{providerId}/models: a built-in provider's models are Zuplo's catalog for it, too many to send in every provider.

An app's consumers have no list of their own: an app has a few, one per client or environment, and include[]=consumers returns them with the app, with the same schema as …/consumers/{consumerId}. A consumer is created in the bucket and linked with a POST of its consumerId to …/ai/apps/{appId}/consumers, and it is changed and deleted at …/consumers/{consumerId}, never in the app's body.

Code
GET /v4/buckets/{bucketId}/ai/apps/{appId}?include[]=consumers

Code
POST /v4/buckets/{bucketId}/consumers?include[]=apiKey
Content-Type: application/json

{ "name": "acme-corp" }

Code
GET /v4/buckets/{bucketId}/ai/apps/{appId}?includeConsumers=true

Code
POST /v4/buckets/{bucketId}/consumers?withApiKey=true

Code
{
  "id": "config_Kx7gDiGsr1c2tOOUW5kpmXZn",
  "name": "Support bot",
  "consumers": null,
  …
}

Code
POST /v4/buckets/{bucketId}/consumers
Content-Type: application/json

{ "name": "acme-corp", "initialApiKey": {} }