Apps

An app is one client of the AI Gateway, such as a product feature, a service or an agent. It has its own policies (authentication, model routing, budgets, guardrails, caching and tracing), and belongs to exactly one pool. A new app starts with a copy of its pool's policy template. Apps are listed and created at …/ai/apps: set poolId when you create one, and filter the list by poolId to see a pool's apps.

An app's API keys belong to its consumers, one for each client or environment that calls it. Create a consumer in the bucket (POST …/consumers), then link it to the app by its ID (POST …/ai/apps/{appId}/consumers with its consumerId). The app returns its linked consumers in consumers.

List apps

GET

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

/v4/buckets/{bucketId}/ai/apps

Lists the gateway's apps, oldest first. Filter by poolId to list the apps of one pool. Apps in its sub-pools are not included.

List apps › path Parameters

bucketId

string · maxLength: 64 · required

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

List apps › query Parameters

poolId

string · maxLength: 64

Only return the apps directly in this pool.

include[]

string[] · maxItems: 1 · unique · style: form · explode: true

What else to return with each app. consumers returns the consumers linked to the app in consumers, which is null otherwise.

Enum values:

consumers

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 apps › Responses

A page of apps.

AiAppList

AiApp[] · required

The apps 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/apps

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

Example Responses

{
  "data": [
    {
      "id": "config_Kx7gDiGsr1c2tOOUW5kpmXZn",
      "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
      "poolId": "config_IM1F8Z4rUT6rDPhabvfnrt27",
      "name": "Support bot",
      "baseUrl": "https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn",
      "policies": [
        {
          "type": "auth",
          "enabled": true,
          "authHeader": "authHeader",
          "authScheme": "authScheme",
          "cacheTtlSeconds": 0,
          "credentialPassthrough": true
        }
      ],
      "consumers": [
        {
          "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
          "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
          "name": "acme-corp",
          "description": "Acme Corp",
          "tags": {
            "plan": "gold"
          },
          "metadata": {
            "customerId": "cus_9s6XKzkNRiz8i3",
            "plan": "gold",
            "seats": 25
          },
          "managers": [
            {
              "email": "[email protected]",
              "sub": "google-oauth2|113533232396018044159"
            }
          ],
          "createdOn": "2024-08-25T15:00:00Z",
          "updatedOn": "2024-08-25T15:00:00Z"
        }
      ],
      "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 app

POST

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

/v4/buckets/{bucketId}/ai/apps

Creates an app in the pool given by poolId, which cannot be changed later. Without policies, the app starts with a copy of the pool's policy template. Creating an app does not issue a key.

Create an app › path Parameters

bucketId

string · maxLength: 64 · required

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

Create an app › query Parameters

include[]

string[] · maxItems: 1 · unique · style: form · explode: true

What else to return with each app. consumers returns the consumers linked to the app in consumers, which is null otherwise.

Enum values:

consumers

Create an app › Request Body

A new app.

CreateAiAppRequest

poolId

string · maxLength: 64 · required

The pool the app belongs to. Cannot be changed later.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

name

string · minLength: 1 · maxLength: 128 · required

The app's display name.

AiPolicyInput[] · maxItems: 30

The app's policies, in the order they run, auth or internal-only first. Omit to start from a copy of the pool's policy template.

Create an app › Responses

The app was created.

One client of the AI Gateway, with its own keys and policies.

AiApp

id

string · required

The app ID.

Example: config_Kx7gDiGsr1c2tOOUW5kpmXZn

bucketId

string · required

The bucket (gateway) the app belongs to.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

poolId

string · required

The pool the app belongs to.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

name

string · required

The app's display name.

Example: Support bot

baseUrl

string | null · uri · required

Where the app's clients send OpenAI- and Anthropic-compatible requests, authenticated with one of the app's API keys. Null until the gateway is deployed.

Example: https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn

AiPolicy[] · required

The app's policies, in the order they run: authentication, model routing, budgets, guardrails, caching and tracing. The budgets of the app's pools and of the gateway apply as well.

array | null · required

The consumers linked to the app, in the order they were linked: one for each client or environment that calls the app with its own key. Null unless include[] has consumers. Link a consumer with POST …/ai/apps/{appId}/consumers, unlink it with DELETE …/ai/apps/{appId}/consumers/{consumerId}, and change it at …/consumers/{consumerId}. Empty for a new app.

createdOn

string · date-time · required

When the app was created.

updatedOn

string · date-time · required

When the app was last changed.

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

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/ai/apps \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Support bot",
  "poolId": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "policies": [
    {
      "type": "auth"
    },
    {
      "type": "model-filtering",
      "completions": {
        "allowList": [
          "openai1/gpt-4o-mini",
          "anthropic1/claude-haiku-4-5"
        ]
      }
    },
    {
      "type": "fallback-model",
      "completions": {
        "fallback": "anthropic1/claude-haiku-4-5"
      }
    },
    {
      "type": "metering",
      "budgetRules": [
        {
          "budgetBy": "app",
          "limits": [
            {
              "meter": "requests",
              "period": "daily",
              "action": "block",
              "value": 100000
            }
          ]
        }
      ]
    }
  ]
}'

Example Request Body

{
  "name": "Support bot",
  "poolId": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "policies": [
    {
      "type": "auth"
    },
    {
      "type": "model-filtering",
      "completions": {
        "allowList": [
          "openai1/gpt-4o-mini",
          "anthropic1/claude-haiku-4-5"
        ]
      }
    },
    {
      "type": "fallback-model",
      "completions": {
        "fallback": "anthropic1/claude-haiku-4-5"
      }
    },
    {
      "type": "metering",
      "budgetRules": [
        {
          "budgetBy": "app",
          "limits": [
            {
              "meter": "requests",
              "period": "daily",
              "action": "block",
              "value": 100000
            }
          ]
        }
      ]
    }
  ]
}

json

application/json

Example Responses

{
  "id": "config_Kx7gDiGsr1c2tOOUW5kpmXZn",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "poolId": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "name": "Support bot",
  "baseUrl": "https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn",
  "policies": [
    {
      "type": "auth",
      "enabled": true,
      "authHeader": "authHeader",
      "authScheme": "authScheme",
      "cacheTtlSeconds": 0,
      "credentialPassthrough": true
    }
  ],
  "consumers": [
    {
      "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
      "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
      "name": "acme-corp",
      "description": "Acme Corp",
      "tags": {
        "plan": "gold"
      },
      "metadata": {
        "customerId": "cus_9s6XKzkNRiz8i3",
        "plan": "gold",
        "seats": 25
      },
      "managers": [
        {
          "email": "[email protected]",
          "sub": "google-oauth2|113533232396018044159"
        }
      ],
      "createdOn": "2024-08-25T15:00:00Z",
      "updatedOn": "2024-08-25T15:00:00Z"
    }
  ],
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Get an app

GET

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

/v4/buckets/{bucketId}/ai/apps/{appId}

Returns an app, the base URL its clients call and its policies. Add include[]=consumers for its consumers.

Get an app › path Parameters

bucketId

string · maxLength: 64 · required

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

appId

string · maxLength: 64 · required

The app ID (config_…).

Get an app › query Parameters

include[]

string[] · maxItems: 1 · unique · style: form · explode: true

What else to return with each app. consumers returns the consumers linked to the app in consumers, which is null otherwise.

Enum values:

consumers

Get an app › Responses

The app.

One client of the AI Gateway, with its own keys and policies.

AiApp

id

string · required

The app ID.

Example: config_Kx7gDiGsr1c2tOOUW5kpmXZn

bucketId

string · required

The bucket (gateway) the app belongs to.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

poolId

string · required

The pool the app belongs to.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

name

string · required

The app's display name.

Example: Support bot

baseUrl

string | null · uri · required

Where the app's clients send OpenAI- and Anthropic-compatible requests, authenticated with one of the app's API keys. Null until the gateway is deployed.

Example: https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn

AiPolicy[] · required

The app's policies, in the order they run: authentication, model routing, budgets, guardrails, caching and tracing. The budgets of the app's pools and of the gateway apply as well.

array | null · required

createdOn

string · date-time · required

When the app was created.

updatedOn

string · date-time · required

When the app was last changed.

GET/v4/buckets/{bucketId}/ai/apps/{appId}

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

Example Responses

{
  "id": "config_Kx7gDiGsr1c2tOOUW5kpmXZn",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "poolId": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "name": "Support bot",
  "baseUrl": "https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn",
  "policies": [
    {
      "type": "auth",
      "enabled": true,
      "authHeader": "authHeader",
      "authScheme": "authScheme",
      "cacheTtlSeconds": 0,
      "credentialPassthrough": true
    }
  ],
  "consumers": [
    {
      "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
      "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
      "name": "acme-corp",
      "description": "Acme Corp",
      "tags": {
        "plan": "gold"
      },
      "metadata": {
        "customerId": "cus_9s6XKzkNRiz8i3",
        "plan": "gold",
        "seats": 25
      },
      "managers": [
        {
          "email": "[email protected]",
          "sub": "google-oauth2|113533232396018044159"
        }
      ],
      "createdOn": "2024-08-25T15:00:00Z",
      "updatedOn": "2024-08-25T15:00:00Z"
    }
  ],
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Update an app

PATCH

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

/v4/buckets/{bucketId}/ai/apps/{appId}

Updates an app with JSON Merge Patch semantics: omitted properties are unchanged, null clears, and arrays such as policies are replaced as a whole, so send the complete list in the order the policies run. An API key or other credential in a policy you send back without it is kept. An app cannot move to another pool.

Fails with 409 when it changes or removes a policy that the pool's template does not let apps change or remove.

Update an app › path Parameters

bucketId

string · maxLength: 64 · required

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

appId

string · maxLength: 64 · required

The app ID (config_…).

Update an app › query Parameters

include[]

string[] · maxItems: 1 · unique · style: form · explode: true

What else to return with each app. consumers returns the consumers linked to the app in consumers, which is null otherwise.

Enum values:

consumers

Update an app › Request Body

Changes to an app (JSON Merge Patch).

UpdateAiAppRequest

name

string · minLength: 1 · maxLength: 128

The app's display name.

AiPolicyInput[] · maxItems: 30

Replaces all of the app's policies, in the order they run. Policies that the pool's template does not let apps change or remove must stay as they are.

Update an app › Responses

The updated app.

One client of the AI Gateway, with its own keys and policies.

AiApp

id

string · required

The app ID.

Example: config_Kx7gDiGsr1c2tOOUW5kpmXZn

bucketId

string · required

The bucket (gateway) the app belongs to.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

poolId

string · required

The pool the app belongs to.

Example: config_IM1F8Z4rUT6rDPhabvfnrt27

name

string · required

The app's display name.

Example: Support bot

baseUrl

string | null · uri · required

Where the app's clients send OpenAI- and Anthropic-compatible requests, authenticated with one of the app's API keys. Null until the gateway is deployed.

Example: https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn

AiPolicy[] · required

The app's policies, in the order they run: authentication, model routing, budgets, guardrails, caching and tracing. The budgets of the app's pools and of the gateway apply as well.

array | null · required

createdOn

string · date-time · required

When the app was created.

updatedOn

string · date-time · required

When the app was last changed.

PATCH/v4/buckets/{bucketId}/ai/apps/{appId}

curl https://dev-api-v4-main-a471234.zuplo.app/v4/buckets/:bucketId/ai/apps/:appId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "policies": [
    {
      "type": "auth"
    },
    {
      "type": "metering",
      "budgetRules": [
        {
          "budgetBy": "app",
          "limits": [
            {
              "meter": "cost",
              "period": "monthly",
              "action": "block",
              "value": 200
            }
          ]
        }
      ]
    },
    {
      "type": "semantic-cache",
      "ttlSeconds": 600
    }
  ]
}'

Example Request Body

{
  "policies": [
    {
      "type": "auth"
    },
    {
      "type": "metering",
      "budgetRules": [
        {
          "budgetBy": "app",
          "limits": [
            {
              "meter": "cost",
              "period": "monthly",
              "action": "block",
              "value": 200
            }
          ]
        }
      ]
    },
    {
      "type": "semantic-cache",
      "ttlSeconds": 600
    }
  ]
}

json

application/json

Example Responses

{
  "id": "config_Kx7gDiGsr1c2tOOUW5kpmXZn",
  "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "poolId": "config_IM1F8Z4rUT6rDPhabvfnrt27",
  "name": "Support bot",
  "baseUrl": "https://acme-ai-gateway-main-b8e2f1a.zuplo.app/a/Kx7gDiGsr1c2tOOUW5kpmXZn",
  "policies": [
    {
      "type": "auth",
      "enabled": true,
      "authHeader": "authHeader",
      "authScheme": "authScheme",
      "cacheTtlSeconds": 0,
      "credentialPassthrough": true
    }
  ],
  "consumers": [
    {
      "id": "csmr_brw0leTAVw478VFKD4F6OqVI",
      "bucketId": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
      "name": "acme-corp",
      "description": "Acme Corp",
      "tags": {
        "plan": "gold"
      },
      "metadata": {
        "customerId": "cus_9s6XKzkNRiz8i3",
        "plan": "gold",
        "seats": 25
      },
      "managers": [
        {
          "email": "[email protected]",
          "sub": "google-oauth2|113533232396018044159"
        }
      ],
      "createdOn": "2024-08-25T15:00:00Z",
      "updatedOn": "2024-08-25T15:00:00Z"
    }
  ],
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Delete an app

DELETE

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

/v4/buckets/{bucketId}/ai/apps/{appId}

Deletes an app and unlinks its consumers. They stay in the bucket with their keys, which no longer call the app: delete them at …/consumers/{consumerId} to revoke the keys. A repeated delete returns 404, which clients should treat as success.

Delete an app › path Parameters

bucketId

string · maxLength: 64 · required

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

appId

string · maxLength: 64 · required

The app ID (config_…).

Delete an app › Responses

The app was deleted.

No data returned

Pool Members User Apps