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 the tag set of a machine image
Replaces the full key/value tag set of the selected image with the submitted set, as
driven by the editable Tags tab of the image detail page (the panel supports adding,
removing and saving tags as one atomic save). This is a full-replacement PUT: tags absent
from the request are removed, new keys are added, and changed values are overwritten.
Validation: the image must exist in the scope and not be soft-deleted (404 NOT_FOUND
otherwise) and its current state must permit tag updates; the body must be an array of
{key, value} pairs with non-empty unique keys — duplicate keys, empty keys or malformed
entries map to 422 VALIDATION_ERROR; the caller needs contributor/admin/owner rights on
the scope (403 FORBIDDEN).
Async & state: Synchronous (200). The tag set is persisted atomically, updatedAt
is bumped, and the canonical resulting tag list is returned; a resource.updated SSE
frame is emitted for the image with a patch on tags/updatedAt. No long-running
operation is created and the image status is unchanged.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown image; 412 stale
If-Match ETag (concurrent edit of the tag panel); 422 invalid tag entries; 500 internal
failure.
Idempotency/Concurrency: This operation does not use Idempotency-Key; it may be omitted
and a sent one is ignored. The PUT is a full replacement: a repeated identical request writes
the same tag set again (same end state) and bumps version/updatedAt, returning a new ETag,
so a retry that resends the If-Match read before a successful first attempt gets 412.
If-Match with the image's current ETag is used for optimistic concurrency; a mismatch returns
412 PRECONDITION_FAILED and the UI reloads the latest tag set before retrying.
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.
imageId*stringIdentifier of the machine image whose tags are replaced.
If-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
application/json- body
Full replacement tag set for the image.
tags*array<>items <= 50Tags replaced; the canonical persisted tag set is returned.
application/json- response
tags*array<>curl -X PUT "https://example.com/scopes/string/compute/images/string/tags" \ -H "Content-Type: application/json" \ -d '{ "tags": [ { "key": "string", "value": "string" } ] }'{ "tags": [ { "key": "string", "value": "string" } ]}