Pools

A pool groups apps that share a budget, a policy template and people (pools were called "teams" before). The policy template is the list of policies a new app starts with, and says which of them the app may change or remove. Pools can be nested: a sub-pool's budget rules apply in addition to its parent's, and it uses its parent's template unless it has its own.

List AI pools

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/ai/pools

Lists the gateway's pools, oldest first. Filter by parentPoolId to list the sub-pools of one pool.

List AI pools › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

List AI pools › query Parameters

parentPoolId

string · maxLength: 64

Only return the direct sub-pools of this pool.

limit

integer · min: 1 · max: 100

The maximum number of items to return.

Default: 10

offset

integer · min: 0

The number of items to skip before the first item returned.

Default: 0

List AI pools › Responses

A page of pools.

AiPoolList

AiPool[] · required

The pools on this page.

limit

integer · required

The page size that was applied.

offset

integer · required

The number of items skipped before this page.

total

integer · required

The number of items in the whole collection.

hasMore

boolean · required

Whether there are more items after this page.

next

string | null · required

The relative URL of the next page, or null on the last page.

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

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/ai/pools \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "config_IM1F8Z4rUT6rDPhabvfnrt27",
      "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
      "parentPoolId": "parentPoolId",
      "name": "Engineering",
      "budgetRules": [
        {
          "budgetBy": "app",
          "expression": "expression",
          "limits": [
            {
              "meter": "cost",
              "period": "hourly",
              "action": "warn",
              "value": 500
            }
          ]
        }
      ],
      "policyTemplate": [
        {
          "policy": {
            "type": "auth",
            "enabled": true,
            "authHeader": "authHeader",
            "authScheme": "authScheme",
            "cacheTtlSeconds": 0,
            "credentialPassthrough": true
          },
          "canEdit": true,
          "canRemove": true
        }
      ],
      "inheritPolicyTemplate": true,
      "createdOn": "2024-08-25T15:00:00Z",
      "updatedOn": "2024-08-25T15:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "total": 0,
  "hasMore": true,
  "next": "next"
}

json

application/json

Create an AI pool

POST

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}/ai/pools

Creates a pool. Set parentPoolId to create a sub-pool. A sub-pool's budget rules apply in addition to its ancestors' rules, and it uses its parent's policy template unless it has its own.

Create an AI pool › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

Create an AI pool › Request Body

A new pool.

CreateAiPoolRequest

name

string · minLength: 1 · maxLength: 128 · required

The pool's display name.

parentPoolId

string | null · maxLength: 64

Create the pool as a sub-pool of this pool. Omit for a top-level pool. Cannot be changed later.

BudgetRuleInput[] · maxItems: 5

The pool's own budget, for the combined traffic of its apps and sub-pools.

AiPolicyTemplateEntryInput[] · maxItems: 30

The policies new apps in the pool start with, in order. Omit it on a top-level pool to start with auth, which apps can neither change nor remove.

inheritPolicyTemplate

boolean

Use the template of the nearest ancestor that has its own. Only allowed on sub-pools, and defaults to true for them when policyTemplate is omitted.

Create an AI pool › Responses

The pool was created.

A group of apps that share a budget, a policy template and people.

AiPool

id

string · required

The pool ID.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

bucketId

string · required

The bucket (gateway) the pool belongs to.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

parentPoolId

string | null · required

The parent pool, or null for a top-level pool.

name

string · required

The pool's display name.

Example: Engineering

BudgetRule[] · required

The pool's own budget. A budgetBy: app rule limits the combined traffic of every app in the pool and its sub-pools. The budgets of the apps, the parent pools and the gateway apply as well.

AiPolicyTemplateEntry[] · required

The policies a new app in the pool starts with, in order, and what the app may do with each. An app gets a copy when it is created: changing the template does not change existing apps. Empty while inheritPolicyTemplate is true.

inheritPolicyTemplate

boolean · required

When true, the pool uses the template of its nearest ancestor that has its own. Always false for top-level pools.

createdOn

string · date-time · required

When the pool was created.

updatedOn

string · date-time · required

When the pool was last changed.

POST/v4/buckets/{bucketId}/ai/pools

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/ai/pools \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Engineering",
  "budgetRules": [
    {
      "budgetBy": "app",
      "limits": [
        {
          "meter": "cost",
          "period": "monthly",
          "action": "block",
          "value": 500
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth"
      }
    },
    {
      "policy": {
        "type": "model-filtering",
        "completions": {
          "allowList": [
            "openai1/gpt-4o-mini",
            "anthropic1/claude-haiku-4-5"
          ]
        }
      },
      "canEdit": true
    },
    {
      "policy": {
        "type": "metering"
      },
      "canEdit": true
    }
  ]
}'

Example Request Body

{
  "name": "Engineering",
  "budgetRules": [
    {
      "budgetBy": "app",
      "limits": [
        {
          "meter": "cost",
          "period": "monthly",
          "action": "block",
          "value": 500
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth"
      }
    },
    {
      "policy": {
        "type": "model-filtering",
        "completions": {
          "allowList": [
            "openai1/gpt-4o-mini",
            "anthropic1/claude-haiku-4-5"
          ]
        }
      },
      "canEdit": true
    },
    {
      "policy": {
        "type": "metering"
      },
      "canEdit": true
    }
  ]
}

json

application/json

Example Responses

{
  "id": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "parentPoolId": "parentPoolId",
  "name": "Engineering",
  "budgetRules": [
    {
      "budgetBy": "app",
      "expression": "expression",
      "limits": [
        {
          "meter": "cost",
          "period": "hourly",
          "action": "warn",
          "value": 500
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth",
        "enabled": true,
        "authHeader": "authHeader",
        "authScheme": "authScheme",
        "cacheTtlSeconds": 0,
        "credentialPassthrough": true
      },
      "canEdit": true,
      "canRemove": true
    }
  ],
  "inheritPolicyTemplate": true,
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Get an AI pool

GET

https://dev-api-v4-main-a471234.zuplo.app

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

Returns a pool, its budget rules and the policy template that apps created in it start from.

Get an AI pool › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

poolId

string · maxLength: 64 · required

The pool ID (config_…).

Get an AI pool › Responses

The pool.

A group of apps that share a budget, a policy template and people.

AiPool

id

string · required

The pool ID.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

bucketId

string · required

The bucket (gateway) the pool belongs to.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

parentPoolId

string | null · required

The parent pool, or null for a top-level pool.

name

string · required

The pool's display name.

Example: Engineering

BudgetRule[] · required

The pool's own budget. A budgetBy: app rule limits the combined traffic of every app in the pool and its sub-pools. The budgets of the apps, the parent pools and the gateway apply as well.

AiPolicyTemplateEntry[] · required

inheritPolicyTemplate

boolean · required

When true, the pool uses the template of its nearest ancestor that has its own. Always false for top-level pools.

createdOn

string · date-time · required

When the pool was created.

updatedOn

string · date-time · required

When the pool was last changed.

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

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/ai/pools/:poolId \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "parentPoolId": "parentPoolId",
  "name": "Engineering",
  "budgetRules": [
    {
      "budgetBy": "app",
      "expression": "expression",
      "limits": [
        {
          "meter": "cost",
          "period": "hourly",
          "action": "warn",
          "value": 500
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth",
        "enabled": true,
        "authHeader": "authHeader",
        "authScheme": "authScheme",
        "cacheTtlSeconds": 0,
        "credentialPassthrough": true
      },
      "canEdit": true,
      "canRemove": true
    }
  ],
  "inheritPolicyTemplate": true,
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Update an AI pool

PATCH

https://dev-api-v4-main-a471234.zuplo.app

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

Updates a pool with JSON Merge Patch semantics. Arrays such as budgetRules and policyTemplate are replaced as a whole. Changing the template affects only apps created afterwards. parentPoolId cannot be changed.

Update an AI pool › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

poolId

string · maxLength: 64 · required

The pool ID (config_…).

Update an AI pool › Request Body

Changes to a pool (JSON Merge Patch).

UpdateAiPoolRequest

name

string · minLength: 1 · maxLength: 128

The pool's display name.

BudgetRuleInput[] · maxItems: 5

Replaces all of the pool's budget rules.

AiPolicyTemplateEntryInput[] · maxItems: 30

Replaces the pool's policy template. Existing apps keep their policies.

inheritPolicyTemplate

boolean

Use the template of the nearest ancestor that has its own. Only allowed on sub-pools.

Update an AI pool › Responses

The updated pool.

A group of apps that share a budget, a policy template and people.

AiPool

id

string · required

The pool ID.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

bucketId

string · required

The bucket (gateway) the pool belongs to.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

parentPoolId

string | null · required

The parent pool, or null for a top-level pool.

name

string · required

The pool's display name.

Example: Engineering

BudgetRule[] · required

The pool's own budget. A budgetBy: app rule limits the combined traffic of every app in the pool and its sub-pools. The budgets of the apps, the parent pools and the gateway apply as well.

AiPolicyTemplateEntry[] · required

inheritPolicyTemplate

boolean · required

When true, the pool uses the template of its nearest ancestor that has its own. Always false for top-level pools.

createdOn

string · date-time · required

When the pool was created.

updatedOn

string · date-time · required

When the pool was last changed.

PATCH/v4/buckets/{bucketId}/ai/pools/{poolId}

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/ai/pools/:poolId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "budgetRules": [
    {
      "budgetBy": "app",
      "expression": "expression",
      "limits": [
        {
          "meter": "cost",
          "period": "hourly",
          "action": "warn",
          "value": 0.1
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth",
        "enabled": true,
        "authHeader": "Authorization",
        "authScheme": "Bearer",
        "cacheTtlSeconds": 10,
        "credentialPassthrough": false
      },
      "canEdit": false,
      "canRemove": false
    }
  ],
  "inheritPolicyTemplate": true
}'

Example Request Body

{
  "name": "name",
  "budgetRules": [
    {
      "budgetBy": "app",
      "expression": "expression",
      "limits": [
        {
          "meter": "cost",
          "period": "hourly",
          "action": "warn",
          "value": 0.1
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth",
        "enabled": true,
        "authHeader": "Authorization",
        "authScheme": "Bearer",
        "cacheTtlSeconds": 10,
        "credentialPassthrough": false
      },
      "canEdit": false,
      "canRemove": false
    }
  ],
  "inheritPolicyTemplate": true
}

json

Example Responses

{
  "id": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "parentPoolId": "parentPoolId",
  "name": "Engineering",
  "budgetRules": [
    {
      "budgetBy": "app",
      "expression": "expression",
      "limits": [
        {
          "meter": "cost",
          "period": "hourly",
          "action": "warn",
          "value": 500
        }
      ]
    }
  ],
  "policyTemplate": [
    {
      "policy": {
        "type": "auth",
        "enabled": true,
        "authHeader": "authHeader",
        "authScheme": "authScheme",
        "cacheTtlSeconds": 0,
        "credentialPassthrough": true
      },
      "canEdit": true,
      "canRemove": true
    }
  ],
  "inheritPolicyTemplate": true,
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Delete an AI pool

DELETE

https://dev-api-v4-main-a471234.zuplo.app

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

Deletes an empty pool. Fails with 409 while the pool still has apps or sub-pools. A repeated delete returns 404, which clients should treat as success.

Delete an AI pool › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

poolId

string · maxLength: 64 · required

The pool ID (config_…).

Delete an AI pool › Responses

The pool was deleted.

No data returned

Provider Assignments Pool Members