Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Replace a budget definition
Replaces the editable fields of an existing Budget (the budget edit form): the budget name, the
target scope selector, the limit amount in ten-thousandths of the currency unit (amountMinor), the reset period
(MONTHLY|QUARTERLY|ANNUAL), the alert threshold percentages, and the alert channel/target. This is a
full replacement (PUT) of the definition; the live spent/forecast/status/history figures are
derived on read and never supplied by the caller.
Validation: budgetId must reference an existing budget in the scope (otherwise 404 NOT_FOUND);
the body is validated identically to creation (name non-empty, amountMinor a positive integer,
thresholds a non-empty array of percentages in (0,100], alertChannel email|webhook with a matching
alertTarget) — violations map to 422 VALIDATION_FAILED; the caller must hold a billing-management
role on the scope, else 403.
Async & state: Completes inline; returns 202 with an Operation that is already SUCCEEDED (the
budget definition is updated and re-evaluated on the next read).
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown budgetId in the scope; 409
duplicate budget name in the scope; 422 field validation failure; 500 internal failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); the returned
Operation id IS the key, so a
replay maps to the same operation.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
budgetId*stringIdentifier of the budget to replace.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidapplication/json- body
The budget creation form submission payload.
name*stringBudget name (non-empty, unique within the subscription case-insensitively; a duplicate is 409 CONFLICT with field: name).
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255scope*stringTarget scope selector: 'subscription:' (the path's subscription), 'tenant:' (its tenant) or 'project:' (one of the subscription's projects); a bare id of the path scope is accepted and prefixed. Any other selector is 422 VALIDATION_FAILED with field: scope; an update that echoes a stored legacy selector unchanged keeps it.
amountMinor*integerBudget limit amount in ten-thousandths of the subscription currency's unit (the console converts the entered amount). Must be between 1 and 9223372036854775807, otherwise 422 VALIDATION_FAILED with field: amountMinor.
period*stringReset period.
"MONTHLY""QUARTERLY""ANNUAL"thresholds*array<integer>Alert thresholds as whole percentages of the limit; 1 to 10 distinct values between 1 and 500, otherwise 422 VALIDATION_FAILED with field: thresholds.
alertChannel*stringAlert delivery channel kind.
"email""webhook"alertTarget*stringRecipient email address (channel=email) or webhook URL (channel=webhook). Alerts are evaluated and delivered by the alerting service: the recipient becomes a managed notification channel of the project (managedBy: budget:<id>) with one rule per threshold plus a 100 % forecast rule. An email address that is not an active user of the tenant receives a verification link and no alert until it is confirmed; a webhook is signed with the channel's own secret (rotate it on budget-notification-channels to read it). A webhook URL must be an https URL without credentials and not a literal non-public address; any other target is 422 VALIDATION_FAILED with field: alertTarget on create AND update. An email recipient must be a well-formed address, otherwise 422 VALIDATION_FAILED with field: alertTarget.
Budget update accepted; track progress through the returned Operation.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"resourceKind?|Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.
resourceId?|Identifier of the target resource; null until the resource is allocated.
resourceName?|Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).
principalId?|Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.
sourceIp?|Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).
progressPercent?|Best-effort progress; null when the action does not report progress.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.
startedAt?|When the worker began executing; null while PENDING.
finishedAt?|When a terminal state was reached; null while transitional.
createdAt*stringupdatedAt*stringcurl -X PUT "https://example.com/scopes/string/billing/budgets/string" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "scope": "string", "amountMinor": 0, "period": "MONTHLY", "thresholds": [ 0 ], "alertChannel": "email", "alertTarget": "string" }'{ "id": "string", "action": "string", "state": "PENDING", "resourceKind": "string", "resourceId": "string", "resourceName": "string", "principalId": "string", "sourceIp": "string", "progressPercent": 0, "error": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "warning": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "startedAt": "string", "finishedAt": "string", "createdAt": "string", "updatedAt": "string"}