Worlds

List worlds

GET /api/worlds

Query parameters

• pageSize (optional): number of results per page. Defaults to 10. Min 1, max 100.
• cursor (optional): opaque paging cursor from next.
• search (optional): filters by name (case-insensitive).
• sort (optional): allowed values: name (default).
• include (optional): allowed values: relations.

If include=relations is omitted, books is returned as an empty array.

Filtering & sorting

• search matches against world name (case-insensitive).
• sort=name is the only supported sort order right now.

Include relations example

GET /api/worlds?include=relations

Response

200 OK

{
  "count": null,
  "next": "/api/worlds?pageSize=10&cursor=...",
  "previous": null,
  "results": [
    {
      "url": "/api/worlds/99a58f64-10bd-5228-ae0b-46279aa515e9",
      "id": "99a58f64-10bd-5228-ae0b-46279aa515e9",
      "name": "Roshar",
      "system_name": "Rosharan System",
      "books": ["/api/books/d76e8ec4-e5a5-51d2-a788-f6a2d19acfd4"],
      "created_at": "2026-02-19T12:34:56Z",
      "updated_at": "2026-02-19T12:34:56Z"
    }
  ]
}

Error cases

• 400 Bad Request: invalid cursor, sort, or include.

Get a world

GET /api/worlds/{id}

Example

GET /api/worlds/99a58f64-10bd-5228-ae0b-46279aa515e9

Response

200 OK

{
  "url": "/api/worlds/99a58f64-10bd-5228-ae0b-46279aa515e9",
  "id": "99a58f64-10bd-5228-ae0b-46279aa515e9",
  "name": "Roshar",
  "system_name": "Rosharan System",
  "books": ["/api/books/d76e8ec4-e5a5-51d2-a788-f6a2d19acfd4"],
  "created_at": "2026-02-19T12:34:56Z",
  "updated_at": "2026-02-19T12:34:56Z"
}

• 404 Not Found: world id does not exist.