Provider Assignments
A provider assignment is the gateway's choice to use a provider: a routing
label, the provider's models it serves, and the environment variable that
holds the provider's API key. Clients select a model in requests as
<label>/<model>, for example anthropic1/claude-sonnet-4-6, and policies,
fallbacks and load balancing name it the same way. So a label cannot be
changed yet: nothing rewrites the policies that name it. One provider can be
assigned several times, with different labels, models or keys.
The key is never sent to this API. It is an environment variable of the bucket's project, read when the gateway calls the provider, so an assignment belongs to that project and is not shared. An assignment's models can have negotiated prices, which replace the list prices in cost metering and cost budgets.
List AI provider assignments
Lists the providers the gateway routes to, ordered by label. Filter by
providerId to see the assignments of one provider.
path Parameters
bucketIdThe bucket ID (bckt_…). Everything in a bucket is addressed under it.
query Parameters
providerIdOnly return the assignments of this provider.
limitThe maximum number of items to return.
offsetThe number of items to skip before the first item returned.
List AI provider assignments › Responses
A page of AI provider assignments.
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.
Create an AI provider assignment
Assigns a provider to the gateway: requests for <label>/<model> go to the
provider, with the key in the environment variable
apiKeyEnvironmentVariable. A provider can be assigned more than once, with
different labels, models or keys.
The key is never sent to or stored by this API. The variable is read from the bucket's project (its production environment, which serves the gateway), so an assignment belongs to one project and cannot be shared. It is not checked on write: if the variable is missing, the assignment is created, and requests routed to it fail until the variable is set.
label must be unique in the bucket because it is the routing prefix:
requests and policies name the assignment's models <label>/<model>.
apiKeyEnvironmentVariable must be unique in the project too. models are the provider's
models the assignment serves, named as GET …/ai/providers/{providerId}/models
lists them; nothing else is routed to it.
Creating an assignment deploys the gateway: it creates a deployment
(source.type zuplo) of the project's production environment, normally
done within a few minutes. The response does not link to it. To wait until
the assignment is usable, list
GET /v4/projects/{projectId}/deployments?environmentId=… and read the
newest zuplo deployment created after this request until it has
succeeded. That does not guarantee every edge serves the assignment yet:
the gateway may serve the previous version for a while.
During the preview, models must include a model of each kind the provider
offers (completions, embeddings). A list without any model of one kind
answers 501: Zuplo stores an assignment's models per kind, and no model of
a kind still means every model of that kind.
path Parameters
bucketIdThe bucket ID (bckt_…). Everything in a bucket is addressed under it.
Create an AI provider assignment › Request Body
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.
Create an AI provider assignment › Responses
The provider assignment was created.
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.
Get an AI provider assignment
Returns a provider assignment and the models it serves, each with the price the gateway meters it at.
path Parameters
bucketIdThe bucket ID (bckt_…). Everything in a bucket is addressed under it.
assignmentIdThe AI provider assignment ID (aip_…).
Get an AI provider assignment › Responses
The AI provider assignment.
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.
Update an AI provider assignment
Updates a provider assignment with JSON Merge Patch semantics. Omitted
properties are unchanged and null clears a property. providerId cannot
be changed, and neither can label yet: requests and policies name the
assignment's models <label>/<model>, and nothing rewrites them, so a
change of label answers 501. To rotate the key, set the environment
variable to the new key, or point apiKeyEnvironmentVariable at another
variable; as on create, the variable is not checked on write.
models replaces all of the models the assignment serves, so send the
complete list: the current models (with any changes) plus new ones, minus
the ones to remove. Removing a model fails with 409 while a policy of an
app, a user app or a pool template still names it as <label>/<model>.
A change deploys the gateway: like a create, it creates a zuplo
deployment of the production environment: read the newest one,
GET /v4/projects/{projectId}/deployments?environmentId=…&limit=1, until it
has succeeded. That does not guarantee every edge serves the change yet:
the gateway may serve the previous version for a while.
During the preview, a models list without any model of a kind the
provider offers answers 501, as on create.
path Parameters
bucketIdThe bucket ID (bckt_…). Everything in a bucket is addressed under it.
assignmentIdThe AI provider assignment ID (aip_…).
Update an AI provider assignment › Request Body
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.
Update an AI provider assignment › Responses
The updated AI provider assignment.
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.
Delete an AI provider assignment
Deletes a provider assignment and its negotiated prices, and deploys the
gateway. Requests for <label>/<model> fail once the deployment has
succeeded. The provider and the environment variable are kept. Fails with
409 while a policy of an app, a user app or a pool template still names
one of its models. A repeated delete returns 404, which clients should
treat as success.
path Parameters
bucketIdThe bucket ID (bckt_…). Everything in a bucket is addressed under it.
assignmentIdThe AI provider assignment ID (aip_…).
Delete an AI provider assignment › Responses
The provider assignment was deleted.