Copy page

AI Gateway

Mapping from api.zuplo.com

What the portal and Agent Z call today (management-api → gateway-service and tenant-api), and the v4 operation that replaces each call. This is the work list for the backend, and for moving the portal onto v4.

Accounts and projects by ID

Today's URLs name the account and the project (/v1/accounts/{accountName}/projects/{projectName}). v4 addresses both by ID: {accountId} and {projectId} (prj_…). Accounts have an ID today (a UUID, the id in /v1/accounts), and v4 shows it unchanged. Every ID in v4 is the one the service mints, with its prefix or without one (question 33): projects keep tenant-api's prj_, and pools, apps and user apps keep gateway-service's config_ (question 1). Responses carry accountId and projectId instead of accountName and projectName, and buckets are filtered by projectId.

Configurations → pools, apps, user apps

Payload changes:

Members and budgets

People are identified by their Zuplo user ID (user_…) in a field named userId (V4-DATA-5), not by their sub as today. GET /v4/accounts/{accountId}/members?email= (or ?sub=) finds someone's userId. /v1/auth/members takes an email or a sub as user and decides itself whether to add the person or invite them. In v4, someone new is added to the account by email first, which returns their userId at once, and pools and projects take that userId in the next request (next section).

Account members and invitations

The portal invites people with /v1/auth/members and /v1/auth/invites (unified members API), and resends, revokes and accepts invitations with the account-member-invites routes. Both write the same AccountMemberInvite rows. v4 has no invitation resource: adding someone to the account by email creates a member with status: invited and a userId right away (question 5).

The behavior is the same in both, except where the last column says what has to change in tenant-api before v4 can serve it:

Providers and models

An assignment serves the models in its models and nothing else (decision 36). Requests and policies name a model <label>/<model>, as in v1, so a label cannot be changed yet: a change answers 501 until something rewrites the policies that name it. The bucket determines the project, so v4 finds the assignment's project from the bucket instead of the account and project names in the URL.

Payload changes: a provider's type is kebab-case (OpenAI → openai, BedrockMantle → bedrock-mantle, AzureAI → azure-ai), and its id stays the backend's (BedrockMantle, aiprov_…). An assignment's provider and customProviderName become one providerId, envVarName becomes apiKeyEnvironmentVariable, endpointUrl becomes baseUrl, and modelSelections ({ completions, embeddings }) becomes models, one list of names. metadata as a JSON string is gone. Model prices move from per token (inputCostPerToken) to per million tokens (pricing.inputPerMillionTokens), and an assignment's overriddenTokenRateCard becomes the model's negotiatedPricing. The dialect enum google_predict is not exposed.

API keys

A consumer is one credential, as in the key service: an app holds one for each client or environment, and a person one per device. v4 creates them under the app or the person, the app returns its consumers in consumers with include[]=consumers, and consumers and keys carry no appId, userAppId or ownerId. There is no roll endpoint: a POST to a consumer's keys rolls, which is the v1 roll-key behavior. Its other keys expire immediately, or after previousKeyGracePeriodSeconds (a query parameter). Creating an app no longer creates a key implicitly. The caller creates a consumer with include[]=apiKey and gets the key's secret once.

Consumers of any gateway

The public key-bucket API on dev.zuplo.com/v1 manages the consumers of API key authentication. Its key buckets are the v4 buckets, and its consumers and keys move into them.

Payload changes: a consumer's keys are not embedded (include-api-keys, apiKeys[]). List them at …/consumers/{consumerId}/api-keys. A consumer's managers are part of it, managers: [{ email, sub }], set on create and replaced as a whole with a PATCH (question 18). email identifies a manager, so managers added by email alone are in v4, with sub (from your developer portal's identity provider) null until they sign in. Managers have no eusr_… ID and no URLs of their own. metadata takes any JSON object of up to 3 KB (3,072 bytes), as in v1 (question 19). Keys are always masked (maskedKey), and the secret is returned once, when the key is created. keys/$bulk, a key value chosen by the client, tag.{name}=… filters and key-format=visible are not in phase 1, so the developer portal keeps using v1 to show a key (question 16), and neither are updating and deleting a bucket.

Environments and deployments

A v1 "deployment" is an environment: one per Git branch, plus a working copy per person, named by its deploymentName. v4 calls it an environment and gives it an ID. A v4 deployment is one build of an environment, today's deployment version (buildId), and it is created, then read until it is done (open question 31). Both are in the project, which v4 makes a container like a bucket: what it deploys, and its members, are under /v4/projects/{projectId}.

Payload changes:

Where v1 and v4 deliberately differ

Both versions read and write the same rows, and each keeps its own behavior:

During the preview

These answer 501 Not Implemented until the change in requiredChanges ships:

The plan item IDs in requiredChanges (T1, T7, …) can change while v4 is a preview.

Not in v4 phase 1

• Analytics (/v2/analytics/ai-gateway…) and request logs: phase 2, once push vs pull is decided.
• Audit logs (/v1/audit-logs/{bucketId}/…): phase 2. They are append-only, so they use cursor pagination.
• …/configurations/{configurationId}/resolved and user-app/ensure: internal.
• Build logs (/v1/deployments/{deploymentName}/build-logs/{buildId}) and request logs: phase 2. They are append-only, so they use cursor pagination.
• Environment variables (…/environment-variables, …/branches/{branchName}/variables), custom domains and changing a project's default branch ($update-default-branch).
• Self-hosted environments (POST /v1/environments) and the configuration a self-hosted runtime reads (…/configurations, …/local-configurations).