---
title: "List the world's files"
method: GET
path: "/api/v2/world/files"
tags: ["World"]
---

# List the world's files

`GET /api/v2/world/files`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/world/files`
- Auth: one of:
  - API key in header `API-Key`
  - API key in header `API-Key` and API key in header `API-Pin`

Any key. Every live file in the world that this key may see (each with its element's type and id), newest first, and the world's total against its cap. Files on elements answer only where the server has them switched on; elsewhere every files route is a 404.

## Response `200`

The world's files and its total.

- object
  - `data` object[], required
    - `id` string, uuid, required
    - `name` string, required: The file's name as uploaded.
    - `kind` 'pdf' | 'txt' | 'md' | 'json' | 'csv' | 'yaml' | 'toml' | 'zip', required
    - `size` integer, required: Bytes, as the upload host stored them.
    - `label` string, nullable, required: A field of the element's type it belongs to, free text, or null.
    - `added_by` object, required: Who added the file: a member's or a seat's name (the owner's username for the owner's keys), their membership id (null for the owner's keys), and whether an agent added it (a seat, the MCP surface, or a key that declared an agent).
      - `name` string, required
      - `membership` string, uuid, nullable, required
      - `agent` boolean, required
    - `added_at` string, date-time, required
    - `element_type` string, required
    - `element_id` string, uuid, required
  - `used_bytes` integer, required: The world's live files' bytes.
  - `cap_bytes` integer, required: The world's room for files.

## Other responses

- `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise).
- `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`: 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`: 3 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 `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`: 6 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 `429`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `503`
  - added the new `world_full` enum value to the `error/code` response property for the response status `401`
  - …2 more

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