Erase an image
Erases one image from the namespace. Its stored bytes
are deleted before this returns, and no earlier version or deleted
copy is kept. From then on this route’s GET
answers image_erased, judging that starts leaves it out, and
replays, refits and recipe tuning skip every evaluation that sent it
to an engine, and bill nothing for them. A judging call already
under way when you erase may still send it. Stored bytes stop
counting toward bytes_stored_hours from the next hourly sample.
Documents and evaluations keep the image’s reference, its digest,
type and size, and reads mark it "erased": true. A document
judged again names it {"digest": ..., "omitted": "erased"} and is
judged on the rest of its context. A write may still send the
reference, marked or not; a write that sends the image’s bytes again
is image_erased, so an erased image is never stored again in this
namespace. To drop the reference, remove its name from the
document’s images (a patch with null) or send the list without it.
Not covered: copies that clients already downloaded, including a browser’s cache of this route, which allows keeping an image for a year; and what an engine’s provider received when it judged the image, which that provider’s own terms govern. Evaluation exports hold references, never bytes. Text in the evaluation log cannot be erased this way.
Needs a key that can write the namespace. Erasing an erased image
returns its first erasure and changes nothing. A digest the
namespace never held is not_found. Audited as image.erase.
Authorizations
An organization API key. Keys carry a role (read_write or
read_only) and may be restricted to a namespace prefix such as
acme/*, or to one namespace such as acme/prod/tenant_1. A prefix
matches on a / boundary: acme/prod/tenant_1* covers
acme/prod/tenant_1 and everything under acme/prod/tenant_1/,
never acme/prod/tenant_12.
Headers
One key per logical request, reused only on its retries. A key
belongs to one request: within your organization, the same method,
path, query and body. For 24 hours after a successful response, a
request with the key and the same body gets that response back
verbatim, with Idempotent-Replayed: true, and runs nothing. Only a
successful response is kept, so the retry of a request that failed
runs again. While the first request runs or its response is kept,
the key with a different request is idempotency_key_reused (422).
A request sent while one with its key is still running is
rate_limited with Retry-After: 1, without running: retry it to
get the first one's response. In the rare case the key can't be
checked, the request runs as if it had none.
1 - 255Path Parameters
The namespace name, with any / sent as %2F.
Up to 256 bytes. / separates levels of the hierarchy, as in acme/prod/tenant_123. Never exactly . or .., which a URL path can't carry.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+$The image's digest, as its reference's digest holds it. The colon may be sent as is or as %3A.
An image's digest, sha256: and 64 lowercase hex digits. Two images with the same digest are the same bytes.
^sha256:[0-9a-f]{64}$