---
title: "Report a stored file (upload host)"
method: POST
path: "/api/v2/files/uploaded"
tags: ["Files"]
---

# Report a stored file (upload host)

`POST /api/v2/files/uploaded`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/files/uploaded`
- Auth: none required

The upload host's report that a file's bytes are stored and checked: the record goes live with the reported size and counts toward the world's total. For the upload host only: no API-Key; the credential is the header X-OW-Signature, the lowercase hex HMAC-SHA256 of the exact body bytes under the ticket secret, as POST /media/uploaded. A missing or wrong signature is a 401; an unknown tid a 404; the same report again a 204. Files on elements answer only where the server has them switched on; elsewhere every files route is a 404.

## Request body

- object
  - `tid` string, uuid, required: The ticket's id: the upload ticket's for /files/uploaded, the removal ticket's for /files/removed.
  - `bytes` integer, required: The stored object's size.
  - `key` string, required: w/<world>/<element>/<file_id>.<ext>

## Response `204`

Recorded.

## Other responses

- `401`: The X-OW-Signature header is missing or wrong (invalid_credentials).
- `404`: Not found in this world (not_found).
- `409`: The ticket's upload was already reported with other values (code already_reported).
- `422`: The body is not {tid, bytes, key} with the record's own key and a size from 1 to the ticket's max_bytes (invalid_request; `param` names it).
- `429`: 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`: 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`: 6 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 `404`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `409`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `422`
  - …2 more
- **2026-10-20** `4dd5b1cd0687`: 12 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 `404`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `409`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `422`
  - …8 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/files/uploaded/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)