---
title: "List location elements"
method: GET
path: "/api/v2/location"
tags: ["Location"]
---

# List location elements

`GET /api/v2/location`

## Request

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

## Query parameters

- `limit` integer
- `cursor` string
- `expand` string[]
- `fields` string[]
- `name` string
- `name__icontains` string
- `supertype` string
- `subtype` string
- `as` string

## Response `200`

A page, oldest change first (by change_seq, then id). With `?fields=` the body holds only the named keys (not this schema's required set); with `?expand=` each named link holds ElementStub objects instead of ids.

- LocationList
  - `data` Location[], required
    - `type` 'location', required
    - `id` string, uuid, required
    - `name` string, required: Name of the element.
    - `description` string, required: Any kind of details about the element.
    - `supertype` string, required: The top level category to which the element belongs.
    - `subtype` string, required: The sub level category through which the element is further classified.
    - `image_url` string, required: URL to an image representing the element.
    - `form` string, required: Visual and environmental aspects of the location.
    - `function` string, required: Main use, role, or purpose of the location within the world.
    - `political_climate` string, required: Political structure, stability, and dynamics of the location.
    - `customs` string, required: Cultural practices, habits, or festivals.
    - `infrastructure` string, required: Roads, ports, and other physical systems that enable the movement of goods and people.
    - `architecture` string, required: Look, form, and materials used in the built environment and location design.
    - `defensibility` string, required: Qualities of natural, constructed, and implemented defenses at the location.
    - `founding_date` integer, nullable, required: Date on which the location was founded, established, or designated.
    - `elevation` integer, nullable, required: Height or elevation of the location relative to surrounding terrain, in the world's distance unit (World distance_unit).
    - `parent_location` string, uuid, nullable, required: Wider location that this location is part of. A Location's id.
    - `primary_power` string, uuid, nullable, required: Institution that has the highest degree of political control over the location. An Institution's id.
    - `governing_title` string, uuid, nullable, required: Governing figure assigned by the location's primary power. A Title's id.
    - `zone` string, uuid, nullable, required: Zone of interest that is associated with the location. A Zone's id.
    - `rival` string, uuid, nullable, required: Location with an active, traditional, or historical rivalry with this one. A Location's id.
    - `partner` string, uuid, nullable, required: Location with active, cooperative, or historical ties to this one. A Location's id.
    - `populations` string[], required: Distinct collective groups or communities residing within the location. Collective ids.
    - `secondary_powers` string[], required: Institutions with significant political control. Institution ids.
    - `founders` string[], required: Individual(s) who founded or named the location. Character ids.
    - `cults` string[], required: Significant religious constructs practiced or recognized at the location. Construct ids.
    - `delicacies` string[], required: Organisms or other species locally consumed or celebrated as specialty foods. Species ids.
    - `extraction_methods` string[], required: Techniques or strategies used to gather natural resources. Construct ids.
    - `extraction_goods` string[], required: Products and materials that are gathered or obtained. Construct ids.
    - `industry_methods` string[], required: Techniques or workflows used to refine or manufacture goods. Construct ids.
    - `industry_goods` string[], required: Products and materials that are refined or manufactured. Construct ids.
    - `extraction_markets` string[], required: Locations that receive extracted goods through trade, interchange, or seizure. Location ids.
    - `industry_markets` string[], required: Locations that receive industrial goods through trade, interchange, or seizure. Location ids.
    - `currencies` string[], required: Trade media recognized or circulated at the location. Construct ids.
    - `buildings` string[], required: Notable structural objects at the location. Object ids.
    - `building_methods` string[], required: Techniques or systems used to construct structures at the location. Construct ids.
    - `fighters` string[], required: Military units or forces responsible for defending the location. Construct ids.
    - `defensive_objects` string[], required: Objects or installations for defending the location. Object ids.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `change_seq` integer, required: The world change sequence at this element's last write.
    - `created_by` string, uuid, nullable, required: The world membership that created this element, or null when the world's owner did.
    - `changed_by` string, uuid, nullable, required: The world membership that last changed this element, or null when the world's owner (or the server) did, or no write has touched it since doors were recorded.
    - `changed_via` 'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'null', nullable, required: The door of the last change: `seat` (an agent seat), `mcp` (the MCP server), `declared` (the request sent an X-OW-Agent header), `api`, `v1`, `sync` (the mobile app's sync) or `server` (the server, on its own behalf). The first three mean an agent made it. Null: no write since doors were recorded.
    - `known_of` true: Present, and true, only on an element this reader knows of but does not see whole: a guest or player reaches it only because its own Character's sheet links to it (one step out). Such a row keeps `id`, `type`, `name`, `description`, `supertype`, `subtype`, `image_url`, `created_at`, `updated_at` and `change_seq`, and its type's public fields (none for a location); every other field reads as unset (text "", numbers and single links null, multi links [], `created_by`, `changed_by` and `changed_via` null, no extension fields), its files are 404, and search matches only what it keeps. Absent: the element is whole. Any other grant (it names the reader's Character, the reader knows it, it is on the roster, the reader made it) makes it whole; a hidden element is never even a stub, whatever its public fields. Read-only: a write carrying `known_of` is refused (`known_of_not_writable`).
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required: Pass back as `cursor` for the next page; null on the last.

## 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`: A member key sent `as`: view as is the owner's (view_as_owner_only).
- `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 `403`
  - 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, 1 info
  - 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 `422`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `429`
  - …7 more

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