Endpoints

Locations

List wiki-visible locations with their parent ids or read one location with its public description.

Read locations whose hidden_from_wiki value is false in the campaign attached to your key. Every request goes through authentication and follows the same rate limits.

List locations

GET/api/public/v1/locations

You get back a flat list of location metadata, sorted first by manual sort order and then by name. Build a hierarchy with parent_id. To read a description, fetch a single location.

Parameter	Type	Description
`limit`	integer	Optional positive page size. Defaults to 50. Values above 100 are capped at 100.
`cursor`	string	Optional `next_cursor` from the previous page. Omit it for the first page.

Request

curl "https://app.saga20.com/api/public/v1/locations?limit=2" \
  -H "Authorization: Bearer $SAGA20_API_KEY"

List response fields

Inside the response you will find data and pagination. See pagination for how to read another page.

Field	Type	Description
`data`	array of objects	Records on this page, with the fields below.
`data[].id`	string	Entry id. Use it in a single-record request.
`data[].name`	string	Entry name.
`data[].icon`	string or null	Stored icon identifier or emoji, or null when unset.
`data[].hidden_from_wiki`	boolean	Always false for returned entries.
`data[].created_at`	string or null	Creation timestamp, or null.
`data[].updated_at`	string or null	Last update timestamp, or null.
`data[].type`	string	Stored location kind, such as `settlement`. The API returns it without changing the value.
`data[].parent_id`	string or null	Parent location id, or null for a root location. A hidden parent can be absent from list results.
`data[].image_url`	string or null	Public image URL, or null when no image is set.
`pagination`	object	Pagination values for this list.
`pagination.next_cursor`	string or null	Cursor for the next page, or null on the last page.
`pagination.has_more`	boolean	True when another page is available.

Response

{
  "data": [
    {
      "id": "c81d4e0f-3a6b-49d2-b7f5-6e0a2c9d8b14",
      "name": "Greywatch Keep",
      "icon": "world-public:locations/city",
      "hidden_from_wiki": false,
      "created_at": "2026-09-02T18:05:00+00:00",
      "updated_at": "2026-09-25T08:05:12+00:00",
      "type": "settlement",
      "parent_id": "2f6a9b13-e4d7-4c08-9a51-0b7d3e8c5f62",
      "image_url": "https://example.com/greywatch-keep.webp"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Get one location

GET/api/public/v1/locations/{id}

You get back one wiki-visible location along with its public description. Sections meant for the GM only are taken out. For how descriptions are formatted, see what the API returns.

Parameter	Type	Description
`id`	string	Required path parameter. Use a location id from the list response.

When a location is missing, hidden, or belongs to another campaign, you get 404 with {"error":"Entity not found"}.

Request

curl "https://app.saga20.com/api/public/v1/locations/c81d4e0f-3a6b-49d2-b7f5-6e0a2c9d8b14" \
  -H "Authorization: Bearer $SAGA20_API_KEY"

Location response fields

What you get back is the location object itself, with no data wrapper around it.

Field	Type	Description
`id`	string	Entry id. Use it in a single-record request.
`name`	string	Entry name.
`icon`	string or null	Stored icon identifier or emoji, or null when unset.
`hidden_from_wiki`	boolean	Always false for returned entries.
`created_at`	string or null	Creation timestamp, or null.
`updated_at`	string or null	Last update timestamp, or null.
`type`	string	Stored location kind, such as `settlement`. The API returns it without changing the value.
`parent_id`	string or null	Parent location id, or null for a root location. A hidden parent can be absent from list results.
`image_url`	string or null	Public image URL, or null when no image is set.
`description_markdown`	string	Public description as normalized Markdown. Empty when no public description content is available.
`description_text`	string	Matching description without heading or bold markers or images. List and table markers can remain.

Response

{
  "id": "c81d4e0f-3a6b-49d2-b7f5-6e0a2c9d8b14",
  "name": "Greywatch Keep",
  "icon": "world-public:locations/city",
  "hidden_from_wiki": false,
  "created_at": "2026-09-02T18:05:00+00:00",
  "updated_at": "2026-09-25T08:05:12+00:00",
  "type": "settlement",
  "parent_id": "2f6a9b13-e4d7-4c08-9a51-0b7d3e8c5f62",
  "image_url": "https://example.com/greywatch-keep.webp",
  "description_markdown": "A fortress above the old road, held by the **Ashen Compact**.",
  "description_text": "A fortress above the old road, held by the Ashen Compact."
}