---
title: "List a narrative's files"
method: GET
path: "/api/v2/narrative/{id}/files"
tags: ["Narrative"]
---

# List a narrative's files

`GET /api/v2/narrative/{id}/files`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/narrative/{id}/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 that may read the element: a file is seen by whoever may see its element (a guest or player key sees exactly the elements it sees). Newest first. Files never ride on the element: nothing here changes its body, its change_seq or /changes. Files on elements answer only where the server has them switched on; elsewhere every files route is a 404.

## Path parameters

- `id` string, uuid, required

## Response `200`

The element's files.

- 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

## Other responses

- `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise).
- `404`: Not found in this world (not_found).
- `422`: Invalid request: an unknown or malformed query parameter, cursor or id (invalid_request); `param` names the culprit.
- `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`: 5 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 `422`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `429`
  - …1 more
- **2026-10-20** `4dd5b1cd0687`: 10 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 `422`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `429`
  - …6 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/narrative/:id/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/78df39c4c62e?raw)