--- title: "Get a ticket to remove one uploaded image" method: POST path: "/api/v2/media/remove-ticket" tags: ["Media"] --- # Get a ticket to remove one uploaded image `POST /api/v2/media/remove-ticket` ## Request - Base URL: `https://www.onlyworlds.com` - URL: `https://www.onlyworlds.com/api/v2/media/remove-ticket` - Auth: API key in header `API-Key` and API key in header `API-Pin` A write key and its PIN. The image's uploader may remove it, and so may the world's owner key; an agent seat answers as its sponsor. Only images uploaded with a ticket can be removed. Returns a short-lived, single-use ticket, the remove_url to send it to (the upload host's POST /v1/remove), its exp in unix seconds, and how many of this world's elements still show the image. Once the image is removed, its bytes stop counting toward the uploader's image storage. ## Request body - object - `key` string, required: u//: an image uploaded into this world with a ticket. ## Response `200` A ticket for removing one image. Cache-Control: no-store. - object - `ticket` string, required: Opaque to clients: send it to remove_url as Authorization: Bearer . One ticket, one removal. - `remove_url` string, required: Where the removal goes, with the ticket: the upload host's POST /v1/remove (the same host as the upload ticket's upload_url). - `exp` integer, required: Unix seconds after which the ticket is refused (10 minutes after it is issued). - `key` string, required: The object key the ticket removes. - `referenced` integer, required: How many of this world's elements show the image (their image_url ends with the key). Removing the image does not change them: clear or replace their image_url yourself. ## Other responses - `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise). - `403`: The credential is valid but lacks the scope: a read key on a write route (permission_error). Or the key belongs to neither the image's uploader nor the world's owner (permission_error). - `404`: No image under this key that can be removed in this world (not_found): the key is outside u//, the image was not uploaded with a ticket, or it is already removed. - `409`: A removal ticket for this image was issued less than 10 minutes ago and its removal is not yet done (code removal_in_flight, type invalid_request). Or no image is recorded under this key yet while an upload ticket of yours in this world is still open and unreported: the upload may have just finished (code upload_pending, type invalid_request; Retry-After 2). The platform cannot tell which key an open ticket will get, so any key answers upload_pending while you hold one, until it expires (10 minutes); then not_found. Both carry a Retry-After header. - `422`: The body is not a JSON object with a non-empty string `key` (invalid_request, param key). - `429`: Too many failed PIN attempts; see the Retry-After header (rate_limited). Or too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds. - `503`: Image upload is not configured on this server (code media_unavailable, type api_error; no Retry-After). Or the server is busy: every request slot stayed full for 10 s (code server_busy, type api_error); retry after the Retry-After header's seconds. ## Changes - **2026-10-20** `78df39c4c62e`: 7 warning - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `403` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `404` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `409` - …3 more - **2026-10-20** `4dd5b1cd0687`: 14 warning - added the new `character_taken` enum value to the `error/code` response property for the response status `401` - added the new `character_taken` enum value to the `error/code` response property for the response status `403` - added the new `character_taken` enum value to the `error/code` response property for the response status `404` - added the new `character_taken` enum value to the `error/code` response property for the response status `409` - …10 more [Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/media/remove-ticket/post.md) --- [API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/78df39c4c62e?raw)