---
title: "Get a ticket for one image upload"
method: POST
path: "/api/v2/media/ticket"
tags: ["Media"]
---

# Get a ticket for one image upload

`POST /api/v2/media/ticket`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/media/ticket`
- Auth: API key in header `API-Key` and API key in header `API-Pin`

A write key and its PIN (owner, classic, member and agent-seat keys alike). No body. Returns a short-lived, single-use ticket that upload_url accepts for exactly one image upload into this world's prefix. The API never sees the image. Each ticket counts toward the world's daily limit, and each upload toward its account's image storage (1 GB by default).

## Response `201`

A ticket for one image upload. Cache-Control: no-store.

- object
  - `ticket` string, required: Opaque to clients: send it to upload_url as is.
  - `upload_url` string, required: Where the image goes, with the ticket.
  - `prefix` string, required: u/<world_id>/: the object key prefix this world's uploads land under.
  - `max_bytes` integer, required: The most this ticket accepts: the per-image limit, or what the account has left, whichever is smaller.
  - `exp` integer, required: Unix seconds after which the ticket is refused.
  - `uses` 1, required: One ticket, one upload.
  - `issued_to` object, required: Who answers for the upload; it is recorded with the stored image. Owner and classic keys: the owner's account, membership null. A member key: the member's account and membership. An agent seat: its sponsor's account and the seat's id.
    - `account` string, uuid, nullable, required
    - `membership` string, uuid, nullable, required

## 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 account the upload counts against has used all of its image storage (code storage_full, type permission_error); the message names the account's cap.
- `429`: Too many failed PIN attempts (rate_limited), or this world has reached its daily image upload limit (code quota_exceeded). Both carry a Retry-After header. 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`: 4 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 `429`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `503`
- **2026-10-20** `4dd5b1cd0687`: 8 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 `429`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `503`
  - …4 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/media/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/1752622ae8ce?raw)