Schemas
Problem
typeIdentifies the kind of error. https://zup.fail/{slug} for Zuplo errors, https://zup.fail/http-status/{code} for generic ones.
titleThe HTTP reason phrase for status, for example "Not Found".
statusThe HTTP status code.
detailWhat went wrong in this occurrence, suitable to show to a person. Omitted on 500 responses.
instanceThe path of the request that failed.
Correlation data for support. requestId equals the request-id response header.
Present on validation failures; one entry per invalid field.
Present on 501 Not Implemented: the backend changes the operation waits
for, one entry each. detail says why the request cannot be served yet.
ProblemTrace
timestampWhen the error occurred.
requestIdThe ID of the failed request.
ProblemFieldError
locationWhere the invalid value is, for example body.budgetRules[0].limits[1].value or query.limit.
messageWhat is wrong with the value.
ProblemRequiredChange
serviceThe Zuplo service that has to change, for example tenant-api or gateway-service.
planItemThe item of the v4 implementation plan that makes the change, for example
T1. Plan item IDs can change while v4 is a preview: show them to
people, but do not depend on them.
changeWhat has to change.
ProjectType
What a project is. ai-gateway is an AI Gateway, api-gateway an API gateway built from source. New values may be added.
EnvironmentType
The environment of a project. New values may be added.
EnvironmentStatus
Whether an environment serves a deployment. provisioning: no deployment has
succeeded yet, so it has no URL. deploying: a deployment is pending or
running, and the environment serves its live deployment until it succeeds.
live: it serves its live deployment, and nothing is deploying. deleting:
it is being deleted, and requests to it fail. A failed deployment leaves the
environment serving what it served before. An AI Gateway environment reports
none of these: its status is null, and its deployments say where a change
is. New values may be added.
DeploymentStatus
Where a deployment is. pending: it waits for its source to be uploaded, or
to start. running: it is building and rolling out. succeeded: its
environment served it once it was done; the environment's liveDeploymentId
says whether it still does. For an AI Gateway, succeeded means the rollout
finished, not that every edge serves it yet: an edge may serve the previous
version for a while. failed: it did not build or roll out, and its
environment kept serving what it served before. succeeded and failed are
final. New values may be added.
DeploymentSourceType
What a deployment deployed. git: a push to the project's Git repository.
upload: source code uploaded with the CLI or the API. deployment: an
earlier deployment of the same environment, deployed again. zuplo: Zuplo
deployed it, as it does for an AI Gateway when its provider assignments change. New
values may be added.
AccountRole
A person's role in the account. New values may be added.
ProjectRole
A role on a project. admin manages the project, its environments and its
members. developer changes and deploys the preview and development
environments, and reads production. member reads the project. ai-user,
on ai-gateway projects only, uses the AI Gateway's user app with personal
API keys and sees nothing else. New values may be added.
AccountRoleInput
The account role to give a person. ai-user is a project role, so it is not
one: give it on a project. Without role-based access control any value but
admin is a 400. New values may be added.
AccountMemberStatus
Whether a person can use the account yet. invited: they were added and
emailed a link, and have not signed in since; their roles take effect when
they do. active: they have signed in. New values may be added.
ProviderType
The kind of upstream provider. Every built-in provider has its own type;
custom is a custom provider, any OpenAI-compatible endpoint. zuplo-demo is
Zuplo's demo provider. New values may be added.
ProviderAssignmentLabel
^[a-z0-9][a-z0-9._-]…A provider assignment's routing prefix, unique in the bucket. Requests and
policies name its models <label>/<model name>. It cannot be changed yet:
changing it answers 501, because nothing rewrites the policies that name
it.
EnvironmentVariableName
^[A-Z][A-Z0-9_]*$The name of an environment variable of the bucket's project that holds the provider's API key. The gateway reads it from the production environment when it calls the provider, so it is not checked on write: while it is missing, requests routed to the assignment fail. Unique among the project's provider assignments.
ModelRef
^[A-Za-z0-9._-]+/\S+…A model as policies, fallbacks and load balancing name it,
<label>/<model name>: the provider assignment's label, as clients name the
model in requests. References a policy stored before v4 are returned as
they were written.
UserId
A person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
UserSub
The subject the identity provider of a person's Zuplo sign-in assigned them, for
example auth0|… or samlp|…. Read-only: it is set at their first sign-in.
It is not an identifier in v4, where people are their userId.
DeveloperPortalUserSub
The subject your developer portal's identity provider assigned a person who
signs in to the portal, for example google-oauth2|…. Developer portal users
are not Zuplo users and have no userId: this is the named exception to
V4-DATA-5.
ModelKind
What a model is used for. New values may be added.
ModelStatus
Whether a model is current or on its way out. New values may be added.
PoolRole
A role on a pool. admin manages the pool, its apps and members; member can view the pool and use its apps. Neither creates, links, changes or rolls the consumers of the pool's apps, which people who manage the bucket's consumers do; both read them.
BudgetBy
What one budget is counted for. app: one budget for all the traffic the
rule covers, that of an app or everything in a pool or the gateway.
expression: one budget per distinct value of expression, for example per
end user.
BudgetMeter
What a limit measures. cost is in US dollars.
BudgetPeriod
The calendar window (UTC) a limit resets on.
BudgetAction
warn records the breach and lets requests through. block rejects requests until the period resets.
Account
idThe account ID.
nameThe account's name, unique across Zuplo. The portal shows it, and v1 URLs use it. Address the account by id.
createdOnWhen the account was created. Null when Zuplo has no record of it, which can be the case for accounts created before it was recorded.
AccountList
The accounts on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
Project
idThe project ID.
accountIdThe account the project belongs to.
nameThe project's name, unique in the account. It is part of the gateway's URL. Address the project by id.
typeWhat a project is. ai-gateway is an AI Gateway, api-gateway an API gateway built from source. New values may be added.
The bucket of each of the project's environment types, production first.
The environments of one type share it. An ai-gateway project has only a
production environment, so it has one bucket, which is created right after
the project: empty until then.
createdOnWhen the project was created.
updatedOnWhen the project was last changed.
ProjectBucket
idThe bucket ID.
environmentTypeThe environment of a project. New values may be added.
ProjectList
The projects on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateProjectRequest
name^[a-z][a-z0-9-]*[a-z… · requiredThe project's name, unique in the account. Lowercase letters, digits and hyphens. It cannot be changed later.
typeWhat a project is. ai-gateway is an AI Gateway, api-gateway an API gateway built from source. New values may be added.
ProjectMember
projectIdThe project.
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
emailThe person's email address.
nameThe person's display name, if they set one.
roleA role on a project. admin manages the project, its environments and its
members. developer changes and deploys the preview and development
environments, and reads production. member reads the project. ai-user,
on ai-gateway projects only, uses the AI Gateway's user app with personal
API keys and sees nothing else. New values may be added.
ProjectMemberList
The project members on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
UpsertProjectMemberRequest
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
roleA role on a project. admin manages the project, its environments and its
members. developer changes and deploys the preview and development
environments, and reads production. member reads the project. ai-user,
on ai-gateway projects only, uses the AI Gateway's user app with personal
API keys and sees nothing else. New values may be added.
Environment
idThe environment ID.
projectIdThe project the environment belongs to.
nameThe environment's name, unique across Zuplo and the first label of its
URL's host: the project name, the branch and a random suffix. The CLI and
logs show it. Not an identifier; address environments by id.
typeThe environment of a project. New values may be added.
branchThe Git branch the environment deploys, unique among the project's production and preview environments. The production environment's is the project's default branch. Null for a working copy, which deploys what its person edits in the portal.
The person whose working copy this is. Null for production and preview environments.
bucketIdThe bucket the environment keeps its gateway data in, such as consumers and API keys. A project's environments of one type share their bucket: every preview environment uses the project's preview bucket. An AI Gateway keeps its data in its production bucket.
Whether the environment serves a deployment. Null for an AI Gateway
environment: nothing reliably says that every edge of an AI Gateway
serves its newest configuration, so v4 does not report it. Read the
environment's newest deployment
(GET /v4/projects/{projectId}/deployments?environmentId=…&limit=1)
until it has succeeded instead, and send the gateway a request to know
what it serves.
urlThe environment's default URL. Null until its first deployment succeeds.
liveDeploymentIdThe deployment the environment serves, the last one that succeeded. Null until one has.
hasCustomDomainWhether a custom domain points at the environment. An environment with one cannot be deleted.
createdOnWhen the environment was created.
updatedOnWhen the environment last changed.
EnvironmentList
The environments on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateEnvironmentRequest
branch^[^\s~]+$ · requiredThe Git branch the environment deploys, without refs/heads/. It cannot
contain ~ or whitespace, and cannot be changed later.
Deployment
idThe deployment ID.
projectIdThe project the deployment belongs to.
environmentIdThe environment it deploys to.
statusWhere a deployment is. pending: it waits for its source to be uploaded, or
to start. running: it is building and rolling out. succeeded: its
environment served it once it was done; the environment's liveDeploymentId
says whether it still does. For an AI Gateway, succeeded means the rollout
finished, not that every edge serves it yet: an edge may serve the previous
version for a while. failed: it did not build or roll out, and its
environment kept serving what it served before. succeeded and failed are
final. New values may be added.
What a deployment deployed.
createdOnWhen the deployment was created.
finishedOnWhen it succeeded or failed. Null while it is pending or running.
DeploymentWithUpload
idThe deployment ID.
projectIdThe project the deployment belongs to.
environmentIdThe environment it deploys to.
statusWhere a deployment is. pending: it waits for its source to be uploaded, or
to start. running: it is building and rolling out. succeeded: its
environment served it once it was done; the environment's liveDeploymentId
says whether it still does. For an AI Gateway, succeeded means the rollout
finished, not that every edge serves it yet: an edge may serve the previous
version for a while. failed: it did not build or roll out, and its
environment kept serving what it served before. succeeded and failed are
final. New values may be added.
What a deployment deployed.
createdOnWhen the deployment was created.
finishedOnWhen it succeeded or failed. Null while it is pending or running.
Where to upload the source, which is shown only once. Null unless source.type is upload.
DeploymentUpload
urlThe signed URL to PUT the archive to. Never send it anywhere else, or log it.
The headers to send with the PUT, exactly as given. The URL's signature covers them.
expiresOnWhen the URL stops working, five minutes after the deployment was created. The deployment fails if the archive has not arrived by then.
DeploymentSource
typeWhat a deployment deployed. git: a push to the project's Git repository.
upload: source code uploaded with the CLI or the API. deployment: an
earlier deployment of the same environment, deployed again. zuplo: Zuplo
deployed it, as it does for an AI Gateway when its provider assignments change. New
values may be added.
deploymentIdFor deployment, the earlier deployment it deployed again. Null otherwise.
rebuildFor deployment, whether it built that deployment's source again (true) or deployed its build as it was (false). Null otherwise.
The Git commit it was built from. Null when it was not built from a known commit.
DeploymentCommit
shaThe commit SHA.
messageThe commit message. Null for an upload.
authorNameThe commit's author, as Git records them. Null for an upload.
committedOnWhen the commit was made. Null for an upload.
DeploymentList
The deployments on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateDeploymentRequest
environmentIdThe project's environment to deploy to.
What to deploy. type says where it comes from.
DeploymentSourceInput
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · type="upload" | |
| type = object · type="deployment" · requires: deploymentId |
typeSource code you upload.
commitSha^[0-9a-f]+$The Git commit the source is from, when you deploy from a Git checkout. The deployment shows it in source.commit.
UploadSourceInput
typeSource code you upload.
commitSha^[0-9a-f]+$The Git commit the source is from, when you deploy from a Git checkout. The deployment shows it in source.commit.
RedeploySourceInput
typeAn earlier deployment.
deploymentIdThe deployment to deploy again. It must be a deployment of the same environment.
rebuildtrue builds the deployment's source again. false deploys its build as
it is, which is faster and does not change the code that runs. Either way
the new deployment gets the environment's current environment variables.
Defaults to false.
Bucket
idThe bucket ID.
accountIdThe account the bucket belongs to.
nameA friendly name, unique across Zuplo. Not an identifier; address buckets by id.
descriptionWhat the bucket is for.
projectIdThe project the bucket belongs to. Null for a custom bucket.
The environment type of the project the bucket belongs to. Its environments of that type share it. Null for a custom bucket.
createdOnWhen the bucket was created.
updatedOnWhen the bucket was last changed.
BucketList
The buckets on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateBucketRequest
name^[a-z0-9-]+$ · requiredA friendly name, unique across Zuplo, so a name another account uses is a 409. Lowercase letters, digits and hyphens. Names that contain zuplo or start with zup, system or zprj- are reserved for Zuplo and are a 400.
descriptionWhat the bucket is for.
AccountMember
accountIdThe account.
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
The subject their identity provider assigned them, set at their first sign-in. Null while they are invited.
emailThe person's email address. An invited member signs in with it.
nameThe person's display name, if they set one. Null while they are invited.
roleA person's role in the account. New values may be added.
statusWhether a person can use the account yet. invited: they were added and
emailed a link, and have not signed in since; their roles take effect when
they do. active: they have signed in. New values may be added.
invitationExpiresOnWhen the link in the latest invitation email stops working, seven days after it was sent. Null once the member is active.
createdOnWhen the person was added to the account.
AccountMemberList
The account members on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
UpsertAccountMemberRequest
emailThe person's email address. Someone new is invited at this address and signs in with it. Compared case-insensitively, without surrounding whitespace.
roleThe account role to give a person. ai-user is a project role, so it is not
one: give it on a project. Without role-based access control any value but
admin is a 400. New values may be added.
AiBudgetRules
The gateway's own budget. A budgetBy: app rule limits the combined
traffic of every pool, app and user app. A budgetBy: expression rule
gives each distinct value its own budget across the whole gateway, for
example each person with request.user.sub. Empty when the gateway has
no budget of its own.
budgetByWhat one budget is counted for. app: one budget for all the traffic the
rule covers, that of an app or everything in a pool or the gateway.
expression: one budget per distinct value of expression, for example per
end user.
expressionFor budgetBy: expression, what to count separately, for example request.user.sub. Null otherwise.
The limits of this rule.
UpsertAiBudgetRulesRequest
The gateway's budget rules, replacing the ones it has. [] removes them.
budgetByWhat one budget is counted for. app: one budget for all the traffic the
rule covers, that of an app or everything in a pool or the gateway.
expression: one budget per distinct value of expression, for example per
end user.
The limits. At most one per meter, period and action; a warn value must be below the block value for the same meter and period.
expressionRequired for budgetBy: expression; must be omitted otherwise.
AiProvider
idThe provider ID: a built-in provider's name (Anthropic, BedrockRuntime,
…), or a custom provider's ID (aiprov_…).
bucketIdThe bucket that defines the custom provider. Null for a built-in provider.
typeThe kind of upstream provider. Every built-in provider has its own type;
custom is a custom provider, any OpenAI-compatible endpoint. zuplo-demo is
Zuplo's demo provider. New values may be added.
builtInWhether this is one of Zuplo's built-in providers, which are read-only. False for a custom provider.
nameThe provider's display name. It is not a routing prefix; an assignment's label is.
descriptionA note for people managing the gateway.
baseUrlThe upstream endpoint. Null for a built-in provider whose endpoint is set
per assignment (bedrock-mantle, azure-ai, vertex-ai).
createdOnWhen the custom provider was defined. Null for a built-in provider.
updatedOnWhen the custom provider was last changed. Null for a built-in provider.
AiProviderList
The providers on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateAiProviderRequest
nameThe provider's display name, unique among the bucket's custom providers.
baseUrlThe OpenAI-compatible endpoint.
The models the provider offers, each with its kind and prices.
descriptionA note for people managing the gateway.
UpdateAiProviderRequest
nameThe provider's display name, unique among the bucket's custom providers.
descriptionA note for people managing the gateway. Null clears it.
baseUrlThe OpenAI-compatible endpoint.
Replaces all of the models the provider offers. Send the complete list.
AiProviderModel
idThe model ID.
providerIdThe provider that offers the model.
nameThe model's name at the provider, unique per provider. A provider assignment selects the model by this name.
kindWhat a model is used for. New values may be added.
statusWhether a model is current or on its way out. New values may be added.
Prices in US dollars per one million tokens. They drive cost metering and cost budgets. Null means the token type is not priced.
AiProviderModelList
The models on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
AiModelPricing
currencyThe currency of all prices. Always usd.
inputPerMillionTokensPrice of one million input tokens.
outputPerMillionTokensPrice of one million output tokens.
cachedInputPerMillionTokensPrice of one million input tokens read from the provider's prompt cache.
cacheWritePerMillionTokensPrice of one million tokens written to the provider's prompt cache (default lifetime).
cacheWrite1hPerMillionTokensPrice of one million tokens written to the provider's one-hour prompt cache.
AiCustomModelInput
name^\S+$ · requiredThe model's name at the provider. Unique per provider.
kindWhat a model is used for. New values may be added.
Prices in US dollars per one million tokens.
statusWhether a model is current or on its way out. New values may be added.
AiModelPricingInput
inputPerMillionTokensPrice of one million input tokens.
outputPerMillionTokensPrice of one million output tokens.
cachedInputPerMillionTokensPrice of one million cached input tokens. Omit or null to leave unpriced.
cacheWritePerMillionTokensPrice of one million cache-write tokens. Required when cacheWrite1hPerMillionTokens is set.
cacheWrite1hPerMillionTokensPrice of one million one-hour cache-write tokens.
AiProviderAssignment
idThe provider assignment ID.
bucketIdThe bucket (gateway) the assignment belongs to.
providerIdThe provider assigned, a built-in provider's name or a custom provider's ID.
label^[a-z0-9][a-z0-9._-]… · requiredA provider assignment's routing prefix, unique in the bucket. Requests and
policies name its models <label>/<model name>. It cannot be changed yet:
changing it answers 501, because nothing rewrites the policies that name
it.
apiKeyEnvironmentVariable^[A-Z][A-Z0-9_]*$ · requiredThe name of an environment variable of the bucket's project that holds the provider's API key. The gateway reads it from the production environment when it calls the provider, so it is not checked on write: while it is missing, requests routed to the assignment fail. Unique among the project's provider assignments.
baseUrlThe upstream endpoint of this assignment, for providers whose endpoint
depends on the account or region (bedrock-mantle, azure-ai,
vertex-ai), or to override a custom provider's. Null means the
provider's baseUrl.
For azure-ai, the model each Azure deployment serves, keyed by deployment name. Null for other types.
gcpProjectIdFor vertex-ai, the Google Cloud project to bill. Null for other types.
The provider's models the assignment serves, each with the price the gateway meters it at. Only these are routed to it. An assignment made before v4 that selects no model of a kind serves every model of that kind the provider offers, including models added later, and lists them all here; its first change through v4 stores the list it is sent.
createdOnWhen the assignment was created.
updatedOnWhen the assignment was last changed.
AiProviderAssignmentList
The provider assignments on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
AiProviderAssignmentModel
nameThe model's name at the provider, as GET …/ai/providers/{providerId}/models lists it.
ref^[A-Za-z0-9._-]+/\S+… · requiredA model as policies, fallbacks and load balancing name it,
<label>/<model name>: the provider assignment's label, as clients name the
model in requests. References a policy stored before v4 are returned as
they were written.
kindWhat a model is used for. New values may be added.
statusWhether a model is current or on its way out. New values may be added.
Prices in US dollars per one million tokens. They drive cost metering and cost budgets. Null means the token type is not priced.
The prices this assignment negotiated with the provider, which replace
the list prices in pricing. Null when it has none, and always for a
custom provider's model.
AiNegotiatedPricing
inputPerMillionTokensPrice of one million input tokens.
outputPerMillionTokensPrice of one million output tokens.
cachedInputPerMillionTokensPrice of one million cached input tokens.
cacheWritePerMillionTokensPrice of one million cache-write tokens.
cacheWrite1hPerMillionTokensPrice of one million one-hour cache-write tokens.
CreateAiProviderAssignmentRequest
providerIdThe provider to assign, a built-in provider's name or a custom provider's ID.
label^[a-z0-9][a-z0-9._-]… · requiredA provider assignment's routing prefix, unique in the bucket. Requests and
policies name its models <label>/<model name>. It cannot be changed yet:
changing it answers 501, because nothing rewrites the policies that name
it.
apiKeyEnvironmentVariable^[A-Z][A-Z0-9_]*$ · requiredThe name of an environment variable of the bucket's project that holds the provider's API key. The gateway reads it from the production environment when it calls the provider, so it is not checked on write: while it is missing, requests routed to the assignment fail. Unique among the project's provider assignments.
The provider's models the assignment serves, named as
GET …/ai/providers/{providerId}/models lists them. A model the provider
does not offer is a 400.
baseUrlThe upstream endpoint. Required for bedrock-mantle, azure-ai and
vertex-ai; for a custom provider, omit it to use the provider's.
For azure-ai, the model each Azure deployment serves, keyed by deployment name.
gcpProjectIdFor vertex-ai, the Google Cloud project to bill.
UpdateAiProviderAssignmentRequest
label^[a-z0-9][a-z0-9._-]…A provider assignment's routing prefix, unique in the bucket. Requests and
policies name its models <label>/<model name>. It cannot be changed yet:
changing it answers 501, because nothing rewrites the policies that name
it.
apiKeyEnvironmentVariable^[A-Z][A-Z0-9_]*$The name of an environment variable of the bucket's project that holds the provider's API key. The gateway reads it from the production environment when it calls the provider, so it is not checked on write: while it is missing, requests routed to the assignment fail. Unique among the project's provider assignments.
baseUrlThe upstream endpoint. Null switches back to the provider's.
For azure-ai, replaces the deployment-to-model map.
gcpProjectIdFor vertex-ai, the Google Cloud project to bill.
Replaces all of the models the assignment serves. Send the complete list.
AiProviderAssignmentModelInput
name^\S+$ · requiredThe model's name at the provider, as GET …/ai/providers/{providerId}/models lists it.
The assignment's own prices for a built-in provider's model, in US dollars per one million tokens. Set only the rates that differ from the list price; the others stay at the list price. Not allowed on a custom provider's model, whose prices are the provider's.
AiNegotiatedPricingInput
inputPerMillionTokensPrice of one million input tokens.
outputPerMillionTokensPrice of one million output tokens.
cachedInputPerMillionTokensPrice of one million cached input tokens.
cacheWritePerMillionTokensPrice of one million cache-write tokens.
cacheWrite1hPerMillionTokensPrice of one million one-hour cache-write tokens.
BudgetRule
budgetByWhat one budget is counted for. app: one budget for all the traffic the
rule covers, that of an app or everything in a pool or the gateway.
expression: one budget per distinct value of expression, for example per
end user.
expressionFor budgetBy: expression, what to count separately, for example request.user.sub. Null otherwise.
The limits of this rule.
BudgetLimit
meterWhat a limit measures. cost is in US dollars.
periodThe calendar window (UTC) a limit resets on.
actionwarn records the breach and lets requests through. block rejects requests until the period resets.
valueThe limit, in US dollars for cost, otherwise a count.
BudgetRuleInput
budgetByWhat one budget is counted for. app: one budget for all the traffic the
rule covers, that of an app or everything in a pool or the gateway.
expression: one budget per distinct value of expression, for example per
end user.
The limits. At most one per meter, period and action; a warn value must be below the block value for the same meter and period.
expressionRequired for budgetBy: expression; must be omitted otherwise.
BudgetLimitInput
meterWhat a limit measures. cost is in US dollars.
periodThe calendar window (UTC) a limit resets on.
actionwarn records the breach and lets requests through. block rejects requests until the period resets.
valueThe limit, in US dollars for cost, otherwise a count.
AiPolicy
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · type="auth" · requires: enabled, authHeader, authScheme +2 more | |
| type = object · type="internal-only" · requires: enabled, status, statusText +1 more | |
| type = object · type="metering" · requires: enabled, budgetRules, failOnError | |
| type = object · type="model-filtering" · requires: enabled, completions, embeddings | |
| type = object · type="model-override" · requires: enabled, completions, embeddings | |
| type = object · type="fallback-model" · requires: enabled, completions, embeddings +1 more | |
| type = object · type="load-balancing" · requires: enabled, strategy, stickyBy +3 more | |
| type = object · type="smart-router" · requires: enabled, classifier, modelsByComplexity +6 more | |
| type = object · type="semantic-cache" · requires: enabled, semanticTolerance, ttlSeconds +4 more | |
| type = object · type="prompt-injection" · requires: enabled, appId, model +8 more | |
| type = object · type="dlp" · requires: enabled, rules, customRules +7 more | |
| type = object · type="akamai-firewall" · requires: enabled, configurationId, applicationId +4 more | |
| type = object · type="opik-tracing" · requires: enabled, workspace, projectName +3 more | |
| type = object · type="galileo-tracing" · requires: enabled, projectId, logStreamId +3 more | |
| type = object · type="custom" · requires: enabled, name |
typeThe auth policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
authHeaderThe request header that carries the API key. Must not be Authorization
when credentialPassthrough is on.
authSchemeThe scheme before the key in authHeader. An empty string means the header
holds only the key.
cacheTtlSecondsHow long a key's validation result is cached.
credentialPassthroughForward the caller's Authorization header to the provider as its
credential.
AiPolicyInput
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · type="auth" | |
| type = object · type="internal-only" | |
| type = object · type="metering" | |
| type = object · type="model-filtering" | |
| type = object · type="model-override" | |
| type = object · type="fallback-model" | |
| type = object · type="load-balancing" · requires: models | |
| type = object · type="smart-router" · requires: classifier, modelsByComplexity | |
| type = object · type="semantic-cache" | |
| type = object · type="prompt-injection" | |
| type = object · type="dlp" · requires: rules | |
| type = object · type="akamai-firewall" · requires: configurationId | |
| type = object · type="opik-tracing" · requires: workspace, projectName | |
| type = object · type="galileo-tracing" · requires: projectId, logStreamId | |
| type = object · type="custom" · requires: name |
typeThe auth policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
authHeaderThe request header that carries the API key. Must not be Authorization
when credentialPassthrough is on. Defaults to Authorization.
authScheme^(\$env\([^)]+\)|[!#…The scheme before the key in authHeader. An empty string means the header
holds only the key. Defaults to Bearer.
cacheTtlSecondsHow long a key's validation result is cached. Defaults to 10.
credentialPassthroughForward the caller's Authorization header to the provider as its
credential. Defaults to false.
AiPolicyTemplateEntry
One policy in an app's, user app's or template's list. type says which policy
it is, and the other properties are its options. New types may be added.
canEditWhether apps may change the policy's options.
canRemoveWhether apps may remove or disable the policy.
AiPolicyTemplateEntryInput
One policy. type says which policy it is, and the other properties are its
options. A list holds each type at most once, and custom once per name, so
a policy sent back without its credential keeps the stored one.
canEditWhether apps may change the policy's options. Defaults to false.
canRemoveWhether apps may remove or disable the policy. Defaults to false.
AiAuthPolicy
typeThe auth policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
authHeaderThe request header that carries the API key. Must not be Authorization
when credentialPassthrough is on.
authSchemeThe scheme before the key in authHeader. An empty string means the header
holds only the key.
cacheTtlSecondsHow long a key's validation result is cached.
credentialPassthroughForward the caller's Authorization header to the provider as its
credential.
AiAuthPolicyInput
typeThe auth policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
authHeaderThe request header that carries the API key. Must not be Authorization
when credentialPassthrough is on. Defaults to Authorization.
authScheme^(\$env\([^)]+\)|[!#…The scheme before the key in authHeader. An empty string means the header
holds only the key. Defaults to Bearer.
cacheTtlSecondsHow long a key's validation result is cached. Defaults to 10.
credentialPassthroughForward the caller's Authorization header to the provider as its
credential. Defaults to false.
AiInternalOnlyPolicy
typeThe internal-only policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
statusThe status code returned to a request from outside the gateway.
statusTextThe status text of a rejected request. Null for the standard text of
status.
detailThe detail of a rejected request's problem response. Null when the
response has no detail.
AiInternalOnlyPolicyInput
typeThe internal-only policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
statusThe status code returned to a request from outside the gateway. Defaults to
403.
statusTextThe status text of a rejected request.
detailThe detail of a rejected request's problem response.
AiMeteringPolicy
typeThe metering policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Budgets counted for all of the app's traffic, or per value of an expression (for example per person). The budgets of pools and of the gateway apply as well.
failOnErrorReject a request when its usage cannot be recorded, instead of logging the error.
AiMeteringPolicyInput
typeThe metering policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
Budgets counted for all of the app's traffic, or per value of an expression
(for example per person). The budgets of pools and of the gateway apply as
well. Defaults to [].
failOnErrorReject a request when its usage cannot be recorded, instead of logging the
error. Defaults to false.
AiModelFilteringPolicy
typeThe model-filtering policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Filtering for chat completions, Responses and Anthropic Messages requests. Null when they are not filtered.
Filtering for embeddings requests. Null when they are not filtered.
AiModelFilteringPolicyInput
typeThe model-filtering policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
The models clients may select for one capability: exactly one of allowList and
blockList is set.
The models clients may select for one capability: exactly one of allowList and
blockList is set.
AiModelOverridePolicy
typeThe model-override policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
The override for chat completions, Responses and Anthropic Messages requests. Null when they are not overridden.
The override for embeddings requests. Null when they are not overridden.
AiModelOverridePolicyInput
typeThe model-override policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
The model override for one capability: exactly one of default and force is
set.
The model override for one capability: exactly one of default and force is
set.
AiFallbackModelPolicy
typeThe fallback-model policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Fallbacks for chat completions, Responses and Anthropic Messages requests. Null when they have none.
Fallbacks for embeddings requests. Null when they have none.
fallbackTimeoutSecondsHow long to wait for the model's response headers before trying fallback.
AiFallbackModelPolicyInput
typeThe fallback-model policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
Fallback models for one capability. Set at least one.
Fallback models for one capability. Set at least one.
fallbackTimeoutSecondsHow long to wait for the model's response headers before trying fallback.
Defaults to 60.
AiLoadBalancingPolicy
typeThe load-balancing policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
strategyHow a model is picked for each request. round-robin cycles through the
models, and sticky sends requests with the same key to the same model.
stickyByWhat sticky keys on. user is the caller (request.user.sub),
conversation the conversation's first messages, and expression the value
of expression. Null for round-robin.
expressionFor stickyBy: expression, the value to key on, for example
request.headers.get("x-end-user-id"). Null otherwise.
The models to spread requests across, by capability. Set at least one list.
fallbackTimeoutSecondsHow long to wait for a model to respond before retrying on another.
AiLoadBalancingPolicyInput
typeThe load-balancing policy.
The models to spread requests across, by capability. Set at least one list.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
strategyHow a model is picked for each request. round-robin cycles through the
models, and sticky sends requests with the same key to the same model.
Defaults to round-robin.
stickyByWhat sticky keys on. user is the caller (request.user.sub),
conversation the conversation's first messages, and expression the value
of expression.
expressionFor stickyBy: expression, the value to key on, for example
request.headers.get("x-end-user-id").
fallbackTimeoutSecondsHow long to wait for a model to respond before retrying on another. Defaults
to 60.
AiSmartRouterPolicy
typeThe smart-router policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
The AI Gateway app that classifies prompts. The call runs inside the gateway.
The model used for each complexity the classifier assigns.
routingEnabledRoute by the classification. When off, prompts are still classified but not rerouted, to test the classifier.
The intents the classifier chooses from. Null for the built-in list (code,
summarization, translation, qa, …).
classifierPromptThe system prompt sent to the classifier. Not used with the system-one
dialect. Null for the built-in prompt.
minConfidenceForRoutingThe confidence, from 0 to 1, a classification needs before it reroutes a request.
classifierTimeoutMsHow long to wait for the classifier, in milliseconds, before forwarding the request unclassified.
maxPromptCharsHow many characters of the prompt are sent to the classifier.
AiSmartRouterPolicyInput
typeThe smart-router policy.
The AI Gateway app that classifies prompts. The call runs inside the gateway.
The model used for each complexity the classifier assigns.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
routingEnabledRoute by the classification. When off, prompts are still classified but not
rerouted, to test the classifier. Defaults to true.
The intents the classifier chooses from.
classifierPromptThe system prompt sent to the classifier. Not used with the system-one
dialect.
minConfidenceForRoutingThe confidence, from 0 to 1, a classification needs before it reroutes a
request. Defaults to 0.5.
classifierTimeoutMsHow long to wait for the classifier, in milliseconds, before forwarding the
request unclassified. Defaults to 8000.
maxPromptCharsHow many characters of the prompt are sent to the classifier. Defaults to
8000.
AiSemanticCachePolicy
typeThe semantic-cache policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
semanticToleranceHow similar a prompt must be to match: closer to 0 requires closer similarity.
ttlSecondsHow long a cached response is kept.
recentMessageCountHow many of the conversation's latest messages form the cache key. System messages always count.
maxConversationLengthSkip the cache for conversations with more messages than this. Null for no limit.
namespacePartitions the cache for callers that are not an app. Apps always have a cache of their own. Null when not set.
endpointsThe request shapes the policy applies to.
AiSemanticCachePolicyInput
typeThe semantic-cache policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
semanticToleranceHow similar a prompt must be to match: closer to 0 requires closer
similarity. Defaults to 0.2.
ttlSecondsHow long a cached response is kept. Defaults to 3600.
recentMessageCountHow many of the conversation's latest messages form the cache key. System
messages always count. Defaults to 1.
maxConversationLengthSkip the cache for conversations with more messages than this.
namespacePartitions the cache for callers that are not an app. Apps always have a cache of their own.
endpointsThe request shapes the policy applies to. Defaults to all of them.
AiPromptInjectionPolicy
typeThe prompt-injection policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
appIdRun the classifier on this AI Gateway app, inside the gateway. model must
then be a model it routes, and baseUrl must not be set. Null when an
external API at baseUrl is called.
modelThe tool-calling model that classifies prompts. With appId, a model
reference (openai1/gpt-4o-mini).
baseUrlThe OpenAI-compatible API that runs the classifier, when appId is not set.
Null with appId, or for https://api.openai.com/v1.
executionWhether the classifier runs before the rest of the policies or alongside
them. sequential classifies before the next policy runs; parallel
classifies while the other policies run, still before the request reaches
the model.
recentMessageCountHow many of the conversation's latest messages are classified.
classifierPromptReplaces the built-in system prompt that says what counts as a prompt injection. Null for the built-in prompt.
timeoutMsHow long to wait for the classifier, in milliseconds, before onError
applies.
endpointsThe request shapes the policy applies to.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked.
onErrorWhat happens when the classifier call fails, for example on an invalid API
key, a timeout or an outage. block rejects the request, and allow lets
it through.
AiPromptInjectionPolicyInput
typeThe prompt-injection policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
appIdRun the classifier on this AI Gateway app, inside the gateway. model must
then be a model it routes, and baseUrl must not be set.
modelThe tool-calling model that classifies prompts. With appId, a model
reference (openai1/gpt-4o-mini). Defaults to gpt-4o-mini.
baseUrlThe OpenAI-compatible API that runs the classifier, when appId is not set.
apiKeyThe classifier's credential: the key for baseUrl, or with appId an API
key of that app (omit it when the app runs internal-only). Write-only: it
is never returned, and omitting it keeps the stored value.
executionWhether the classifier runs before the rest of the policies or alongside
them. sequential classifies before the next policy runs; parallel
classifies while the other policies run, still before the request reaches
the model. Defaults to sequential.
recentMessageCountHow many of the conversation's latest messages are classified. Defaults to
1.
classifierPromptReplaces the built-in system prompt that says what counts as a prompt injection.
timeoutMsHow long to wait for the classifier, in milliseconds, before onError
applies. Defaults to 10000.
endpointsThe request shapes the policy applies to. Defaults to all of them.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked. Defaults to
deny.
onErrorWhat happens when the classifier call fails, for example on an invalid API
key, a timeout or an outage. block rejects the request, and allow lets
it through. Defaults to block.
AiDlpPolicy
typeThe dlp policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
What the policy scans for, by direction. Each direction that is set is scanned; at least one must enable a rule.
Detectors of your own.
allowValuesExact values that are never flagged, such as documented test card numbers.
detectionHow much evidence a match needs, for rules that do not set their own.
corroborated also needs a context word near the match, standard is tuned
per type, and aggressive counts every pattern match.
scanToolArgumentsAlso scan tool-call arguments.
How streaming responses are scanned.
endpointsThe request shapes the policy applies to.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked.
onErrorWhat happens when the scanner itself fails. block rejects the request, and
allow lets it through.
AiDlpPolicyInput
typeThe dlp policy.
What the policy scans for, by direction. Each direction that is set is scanned; at least one must enable a rule.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
Detectors of your own. Defaults to [].
allowValuesExact values that are never flagged, such as documented test card numbers.
Defaults to [].
detectionHow much evidence a match needs, for rules that do not set their own.
corroborated also needs a context word near the match, standard is tuned
per type, and aggressive counts every pattern match. Defaults to
standard.
scanToolArgumentsAlso scan tool-call arguments. Defaults to true.
How streaming responses are scanned.
endpointsThe request shapes the policy applies to. Defaults to all of them.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked. Defaults to
deny.
onErrorWhat happens when the scanner itself fails. block rejects the request, and
allow lets it through. Defaults to block.
AiAkamaiFirewallPolicy
typeThe akamai-firewall policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
configurationIdThe AI firewall configuration to use.
applicationIdIdentifies this usage of the firewall. Null when not set.
How streaming responses are checked.
endpointsThe request shapes the policy applies to.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked.
onErrorWhat happens when the firewall check itself fails, for example on an invalid
API key or an outage. block rejects the request, and allow lets it
through.
AiAkamaiFirewallPolicyInput
typeThe akamai-firewall policy.
configurationIdThe AI firewall configuration to use.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
applicationIdIdentifies this usage of the firewall.
apiKeyThe firewall's API key. Required when the policy is added. Write-only: it is never returned, and omitting it keeps the stored value.
How streaming responses are checked.
endpointsThe request shapes the policy applies to. Defaults to all of them.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked. Defaults to
deny.
onErrorWhat happens when the firewall check itself fails, for example on an invalid
API key or an outage. block rejects the request, and allow lets it
through. Defaults to block.
AiOpikTracingPolicy
typeThe opik-tracing policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
workspaceThe Opik workspace.
projectNameThe Opik project that traces are filed under.
baseUrlThe Opik API. Null for https://www.comet.com/opik/api.
endpointsThe request shapes the policy applies to.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked.
AiOpikTracingPolicyInput
typeThe opik-tracing policy.
workspaceThe Opik workspace.
projectNameThe Opik project that traces are filed under.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
baseUrlThe Opik API.
apiKeyThe Opik API key. Required when the policy is added. Write-only: it is never returned, and omitting it keeps the stored value.
endpointsThe request shapes the policy applies to. Defaults to all of them.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked. Defaults to
skip.
AiGalileoTracingPolicy
typeThe galileo-tracing policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
projectIdThe Galileo project that traces are filed under.
logStreamIdThe Galileo log stream.
baseUrlThe Galileo API. Null for https://api.galileo.ai.
endpointsThe request shapes the policy applies to.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked.
AiGalileoTracingPolicyInput
typeThe galileo-tracing policy.
projectIdThe Galileo project that traces are filed under.
logStreamIdThe Galileo log stream.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
baseUrlThe Galileo API.
apiKeyThe Galileo API key. Required when the policy is added. Write-only: it is never returned, and omitting it keeps the stored value.
endpointsThe request shapes the policy applies to. Defaults to all of them.
onUnknownShapeWhat happens to a request whose shape the policy cannot inspect. deny
rejects the request, and skip lets it through unchecked. Defaults to
skip.
AiCustomPolicy
typeThe custom policy.
enabledWhether the policy runs. A disabled policy keeps its place and options.
nameThe policy's name in config/policies.json.
AiCustomPolicyInput
typeThe custom policy.
nameThe policy's name in config/policies.json.
enabledWhether the policy runs. A disabled policy keeps its place and options.
Defaults to true.
AiModelFilter
allowListThe only models clients may select. The first is used when a request names
no model. Null when blockList is set.
blockListModels clients may not select. Every other model on the gateway is allowed.
Null when allowList is set.
AiModelFilterInput
allowListThe only models clients may select. The first is used when a request names no model.
blockListModels clients may not select. Every other model on the gateway is allowed.
AiModelOverride
defaultThe model used when a request names none. Null when force is set.
forceThe model every request uses, whatever it asks for. Null when default is
set.
AiModelOverrideInput
default^[A-Za-z0-9._-]+/\S+…The model used when a request names none.
force^[A-Za-z0-9._-]+/\S+…The model every request uses, whatever it asks for.
AiModelFallback
fallbackThe model tried after a retryable error or a timeout. Null when not set.
quotaFallbackThe model used once a budget with action block is exhausted. Null when not
set.
AiModelFallbackInput
fallback^[A-Za-z0-9._-]+/\S+…The model tried after a retryable error or a timeout.
quotaFallback^[A-Za-z0-9._-]+/\S+…The model used once a budget with action block is exhausted.
AiLoadBalancingModels
completionsModels for chat completions, Responses and Anthropic Messages requests, each listed once. Null when completions are not balanced.
embeddingsModels for embeddings requests, each listed once. Null when embeddings are not balanced.
AiLoadBalancingModelsInput
completionsModels for chat completions, Responses and Anthropic Messages requests, each listed once.
embeddingsModels for embeddings requests, each listed once.
AiSmartRouterClassifier
appIdThe app that runs the classifier. It must not be this app, and must not run a smart router itself.
modelThe model the classifier app uses, a model reference (<label>/<model name>).
dialectThe API the classifier app is called with. chat-completions and messages
(Anthropic Messages) send a prompt; system-one is for classification
models such as Jev.
AiSmartRouterClassifierInput
appIdThe app that runs the classifier. It must not be this app, and must not run a smart router itself.
model^[A-Za-z0-9._-]+/\S+… · requiredThe model the classifier app uses, a model reference (<label>/<model name>).
dialectThe API the classifier app is called with. chat-completions and messages
(Anthropic Messages) send a prompt; system-one is for classification
models such as Jev. Defaults to chat-completions.
apiKeyAn API key of the classifier app, sent as Authorization: Bearer. Omit it
when that app runs the internal-only policy. Write-only: it is never
returned, and omitting it keeps the stored value.
AiModelsByComplexity
lowThe model for low-complexity prompts.
mediumThe model for medium-complexity prompts.
highThe model for high-complexity prompts.
AiModelsByComplexityInput
low^[A-Za-z0-9._-]+/\S+… · requiredThe model for low-complexity prompts.
medium^[A-Za-z0-9._-]+/\S+… · requiredThe model for medium-complexity prompts.
high^[A-Za-z0-9._-]+/\S+… · requiredThe model for high-complexity prompts.
AiSmartRouterIntent
nameThe intent's label, for example code.
descriptionWhat prompts with this intent are about.
AiSmartRouterIntentInput
nameThe intent's label, for example code.
descriptionWhat prompts with this intent are about.
AiDlpRules
What callers send the model (system prompt, messages and tool-call
arguments). Keyed by a data type (id-us-ssn), a group (pii,
secret-aws) or a custom rule's name. The most specific key wins. Null
when requests are not scanned.
What the model sends back, keyed like inbound. Null when responses are not
scanned.
AiDlpRulesInput
What callers send the model (system prompt, messages and tool-call
arguments). Keyed by a data type (id-us-ssn), a group (pii,
secret-aws) or a custom rule's name. The most specific key wins.
What the model sends back, keyed like inbound.
AiDlpRule
actionWhat happens on a match. mask replaces the value, block rejects the
request or ends the response, log only records the match, and off
excludes the type from a broader rule.
detectionHow much evidence a match needs. Overrides the policy's detection.
corroborated also needs a context word near the match, standard is tuned
per type, and aggressive counts every pattern match. Null when the
policy's detection applies.
maskThe replacement for masked text. {type} inserts the detected type.
maskKeepLastKeep this many trailing characters of a masked value and replace the rest
with *, for example for the last four digits of a card. Null when the
whole value is masked.
AiDlpRuleInput
actionWhat happens on a match. mask replaces the value, block rejects the
request or ends the response, log only records the match, and off
excludes the type from a broader rule.
detectionHow much evidence a match needs. Overrides the policy's detection.
corroborated also needs a context word near the match, standard is tuned
per type, and aggressive counts every pattern match.
maskThe replacement for masked text. {type} inserts the detected type.
Defaults to [{type}].
maskKeepLastKeep this many trailing characters of a masked value and replace the rest
with *, for example for the last four digits of a card.
AiDlpCustomRule
nameThe detector's name, used as its key in rules.
patternA JavaScript regular expression source.
contextWords that must appear near a match for corroborated detection.
AiDlpCustomRuleInput
nameThe detector's name, used as its key in rules.
patternA JavaScript regular expression source.
contextWords that must appear near a match for corroborated detection. Defaults
to [].
AiDlpStreaming
modeHow streaming responses are scanned. stream scans chunks as they flow,
buffer scans the whole response once, and off does not scan streams.
boundaryScanScan across chunk boundaries, so a value split over two chunks is still found.
maxCarryCharsHow many trailing characters of a chunk are carried into the next boundary scan.
AiDlpStreamingInput
modeHow streaming responses are scanned. stream scans chunks as they flow,
buffer scans the whole response once, and off does not scan streams.
Defaults to stream.
boundaryScanScan across chunk boundaries, so a value split over two chunks is still
found. Defaults to true.
maxCarryCharsHow many trailing characters of a chunk are carried into the next boundary
scan. Defaults to 512.
AiAkamaiStreamingAccumulation
enabledAccumulate and check streaming responses.
eventsIntervalHow many events are accumulated before each check.
checkIntervalMsCheck on this interval, in milliseconds, instead of by event count. Null when checks go by event count.
AiAkamaiStreamingAccumulationInput
enabledAccumulate and check streaming responses. Defaults to true.
eventsIntervalHow many events are accumulated before each check. Defaults to 5.
checkIntervalMsCheck on this interval, in milliseconds, instead of by event count.
AiEndpointShape
A request shape a policy can inspect. New values may be added.
AiPool
idThe pool ID.
bucketIdThe bucket (gateway) the pool belongs to.
parentPoolIdThe parent pool, or null for a top-level pool.
nameThe pool's display name.
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.
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.
inheritPolicyTemplateWhen true, the pool uses the template of its nearest ancestor that has its own. Always false for top-level pools.
createdOnWhen the pool was created.
updatedOnWhen the pool was last changed.
AiPoolList
The pools on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateAiPoolRequest
nameThe pool's display name.
parentPoolIdCreate the pool as a sub-pool of this pool. Omit for a top-level pool. Cannot be changed later.
The pool's own budget, for the combined traffic of its apps and sub-pools.
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.
inheritPolicyTemplateUse 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.
UpdateAiPoolRequest
nameThe pool's display name.
Replaces all of the pool's budget rules.
Replaces the pool's policy template. Existing apps keep their policies.
inheritPolicyTemplateUse the template of the nearest ancestor that has its own. Only allowed on sub-pools.
AiPoolMember
poolIdThe pool.
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
emailThe person's email address.
nameThe person's display name, if they set one.
roleThe role assigned on this pool, or null if the person only inherits access.
inheritedRoleThe highest role inherited from an ancestor pool, or null.
effectiveRoleA role on a pool. admin manages the pool, its apps and members; member can view the pool and use its apps. Neither creates, links, changes or rolls the consumers of the pool's apps, which people who manage the bucket's consumers do; both read them.
AiPoolMemberList
The pool members on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
UpsertAiPoolMemberRequest
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
roleA role on a pool. admin manages the pool, its apps and members; member can view the pool and use its apps. Neither creates, links, changes or rolls the consumers of the pool's apps, which people who manage the bucket's consumers do; both read them.
AiAppConsumer
appIdThe app.
consumerIdThe consumer.
createdOnWhen the consumer was linked to the app.
UpsertAiAppConsumerRequest
consumerIdA consumer in the app's bucket. It cannot be a person's consumer or one another app holds.
AiApp
idThe app ID.
bucketIdThe bucket (gateway) the app belongs to.
poolIdThe pool the app belongs to.
nameThe app's display name.
baseUrlWhere 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.
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.
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.
createdOnWhen the app was created.
updatedOnWhen the app was last changed.
AiAppList
The apps on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
CreateAiAppRequest
poolIdThe pool the app belongs to. Cannot be changed later.
nameThe app's display name.
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.
UpdateAiAppRequest
nameThe app's display name.
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.
AiUserApp
idThe user app ID.
bucketIdThe bucket (gateway) the user app belongs to.
nameThe user app's display name.
baseUrlWhere personal-key clients (Claude Code, Cursor, scripts) send requests. Null until the gateway is deployed.
The policies every personal-key request runs, in order. The metering
policy's per-person rule (budgetBy: expression on request.user.sub)
sets the limits every person gets. A person's budget changes them for that
person.
createdOnWhen the user app was created.
updatedOnWhen the user app was last changed.
AiUserAppList
The user apps on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
UpdateAiUserAppRequest
nameThe user app's display name.
Replaces all of the user app's policies, in the order they run. Keep the
metering policy's per-person rule to keep personal limits: removing a
limit that a person's budget still changes fails with 409.
AiUserAppUser
userAppIdThe user app.
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
emailThe person's email address.
nameThe person's display name, if they set one.
hasBudgetOverrideWhether the person has limits of their own (…/users/{userId}/budget) instead of the user app's defaults.
The person's limits, as GET …/users/{userId}/budget returns them. Null unless include[] has budget.
AiUserAppUserList
The people on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
AiUserBudget
userAppIdThe user app.
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
The person's own limits. Empty when the defaults apply. Limits that are not listed keep the defaults.
updatedOnWhen the limits were last set, or null if they never were.
UpsertAiUserBudgetRequest
Replaces the person's own limits. Each must match a cost limit with action block in the user app's per-person budget rule. [] puts the person back on the defaults.
AiUserAppUsage
userAppIdThe user app.
userIdA person, identified by their Zuplo user ID (user_…). Zuplo assigns it when
the person is first added to an account, before they ever sign in, and it
never changes. Every userId and ownerId in v4 is one.
Usage per limit.
measuredOnHow fresh the numbers are. Usage is aggregated asynchronously and can lag by a few seconds.
AiUsageLimit
meterWhat a limit measures. cost is in US dollars.
periodThe calendar window (UTC) a limit resets on.
actionwarn records the breach and lets requests through. block rejects requests until the period resets.
limitThe limit that applies to this person, or null if it cannot be determined right now.
usedUsage so far in the current period.
remainingWhat is left before the limit, or null when limit is null.
resetsOnWhen the current period ends.
sourceWhether the limit comes from the per-person budget rule (default) or the person's own budget, or null when unknown.
ApiKey
idThe key ID. Not the secret.
consumerIdThe consumer the key belongs to.
descriptionWhat the key is used for.
maskedKeyThe first and last characters of the secret, to recognize the key.
expiresOnWhen the key stops working, or null if it never expires.
createdOnWhen the key was created.
updatedOnWhen the key was last changed.
ApiKeyWithSecret
idThe key ID. Not the secret.
consumerIdThe consumer the key belongs to.
descriptionWhat the key is used for.
maskedKeyThe first and last characters of the secret, to recognize the key later.
expiresOnWhen the key stops working, or null if it never expires.
createdOnWhen the key was created.
updatedOnWhen the key was last changed.
secretThe full API key. Send it as Authorization: Bearer <secret>. Returned only in this response.
ApiKeyList
The API keys on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
ApiKeySecret
apiKeyIdThe key the secret belongs to.
secretThe full API key. Send it as Authorization: Bearer <secret>.
CreateConsumerApiKeyRequest
descriptionWhat the key is used for.
expiresOnWhen the key stops working. Omit for a key that never expires.
UpdateApiKeyRequest
descriptionWhat the key is used for. Null clears it.
expiresOnWhen the key stops working. Null removes the expiry.
Consumer
idThe consumer ID.
bucketIdThe bucket the consumer belongs to.
nameThe consumer's name, unique in the bucket. For a consumer the bucket holds,
the API key authentication policy sets request.user.sub to it. Generated
for the consumers of apps and people.
descriptionWho or what the consumer is.
Key-value pairs to organize and find consumers. Empty when there are none.
Your data for your own code: the API key authentication policy passes it
to your gateway as request.user.data. Any JSON values, at most 3 KB
(3,072 bytes) as JSON. Empty when there is none.
The people who manage the consumer's keys in your developer portal, by email. Empty when there are none, and always empty for the consumers of apps and people.
createdOnWhen the consumer was created.
updatedOnWhen the consumer was last changed.
ConsumerList
The consumers on this page.
limitThe page size that was applied.
offsetThe number of items skipped before this page.
totalThe number of items in the whole collection.
hasMoreWhether there are more items after this page.
nextThe relative URL of the next page, or null on the last page.
ConsumerWithApiKey
idThe consumer ID.
bucketIdThe bucket the consumer belongs to.
nameThe consumer's name, unique in the bucket.
descriptionWho or what the consumer is.
Key-value pairs to organize and find consumers. Empty when there are none.
Your data for your own code, passed to your gateway as request.user.data. Any JSON values, at most 3 KB (3,072 bytes) as JSON. Empty when there is none.
The people who manage the consumer's keys in your developer portal, by email. Empty when there are none, and always empty for the consumers of apps and people.
createdOnWhen the consumer was created.
updatedOnWhen the consumer was last changed.
The consumer's first key, with its secret, which is shown only once. Null unless include[] had apiKey.
CreateConsumerRequest
name^[a-z0-9-]+$ · requiredA name, unique in the bucket, that cannot be changed later: lowercase
letters, digits and hyphens. The API key authentication policy sets
request.user.sub to it.
descriptionWho or what the consumer is.
Up to five key-value pairs to organize and find consumers. Keys are at most 64 characters.
Your data for your own code: the API key authentication policy passes it
to your gateway as request.user.data. Any JSON values, at most 3 KB
(3,072 bytes) as JSON. Keys are at most 64 characters.
The people who manage the consumer's keys in your developer portal, by email, at most 100. They see its keys there once they sign in with that address.
CreateAiUserConsumerRequest
descriptionWhere the person uses the consumer's keys, for example their laptop.
UpdateConsumerRequest
descriptionWho or what the consumer is. Null clears it.
Tags to set, merged key by key. A key set to null is removed, and null removes every tag. A consumer has at most five tags.
Metadata to set, merged as a JSON Merge Patch. A key set to null is removed, an object is merged into the object it replaces, any other value replaces the key's value, and null removes all metadata. The result is at most 3 KB (3,072 bytes) as JSON.
All of the consumer's managers, replacing the current ones: send the
complete list, and [] to remove them all. Only a consumer the bucket
holds has managers; on any other consumer this is a 400.
ConsumerManager
emailThe person's email address. The developer portal shows them the consumer's keys when they sign in with it.
Their subject in your developer portal's identity provider. Null until they first sign in to the portal.