Endpoints

Characters

List wiki-visible characters or read one character with its public description as Markdown and text.

Read the characters whose hidden_from_wiki value is false, in the campaign tied to your key. Every request relies on authentication and the common rate limits.

List characters

GET/api/public/v1/characters

Gives back character metadata, sorted first by manual order and next by name. Player characters show up alongside NPCs. To read its description, fetch a single character.

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/characters?limit=2" \
  -H "Authorization: Bearer $SAGA20_API_KEY"

List response fields

Inside the response you get data plus pagination. To load a further page, consult pagination.

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[].is_player_character`	boolean	True for a player character. False for an NPC.
`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": "a4f1b6d2-0e5c-4b7a-8c33-1d9e2f7a6b50",
      "name": "Nyra Vael",
      "icon": "saga20:mage",
      "hidden_from_wiki": false,
      "created_at": "2026-09-02T18:00:11+00:00",
      "updated_at": "2026-09-25T08:04:02+00:00",
      "is_player_character": true
    },
    {
      "id": "5e2c8a91-7d34-4f0b-a6e1-b03c9d4f1a27",
      "name": "Warden Ossric",
      "icon": null,
      "hidden_from_wiki": false,
      "created_at": "2026-09-09T20:15:44+00:00",
      "updated_at": "2026-09-18T07:42:30+00:00",
      "is_player_character": false
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Get one character

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

Gives back one character that the wiki shows, along with its public description. Any sections meant only for the GM are taken out. The way descriptions are formatted matches what the API returns.

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

When a character 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/characters/a4f1b6d2-0e5c-4b7a-8c33-1d9e2f7a6b50" \
  -H "Authorization: Bearer $SAGA20_API_KEY"

Character response fields

You receive the character object itself as the response, 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.
`is_player_character`	boolean	True for a player character. False for an NPC.
`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": "a4f1b6d2-0e5c-4b7a-8c33-1d9e2f7a6b50",
  "name": "Nyra Vael",
  "icon": "saga20:mage",
  "hidden_from_wiki": false,
  "created_at": "2026-09-02T18:00:11+00:00",
  "updated_at": "2026-09-25T08:04:02+00:00",
  "is_player_character": true,
  "description_markdown": "## Appearance\n\nNyra wears a silver travelling cloak and carries a **cold iron key**.\n\n- Tiefling wizard\n\n- Sworn to the Ashen Compact",
  "description_text": "Appearance\n\nNyra wears a silver travelling cloak and carries a cold iron key.\n\n- Tiefling wizard\n\n- Sworn to the Ashen Compact"
}