# Soulbound: Online — public game data API

> Free, read-only HTTP API for the game data behind Soulbound: Online, published
> by Spiderware, the studio that makes the game. Items, abilities, relics,
> followers, the stat vocabulary and the artwork. No signup, no cost, no write
> path. Anyone may build on it.

Base URL: https://api.soulbound.tools
Dataset version: 2026-08-07.1 (published 2026-08-07T17:52:21Z)
Record counts: items: 1452, abilities: 39, relics: 692, followers: 54, stats: 58

## Start here

- [OpenAPI 3.1 document](https://api.soulbound.tools/v1/openapi.json): the exact, complete,
  machine-readable description. Generated from the Worker's own route table, so
  it cannot drift from what is served. Build your tools from this.
- [Human reference](https://api.soulbound.tools/docs): the same thing with worked examples,
  an agent setup guide and a pasteable system prompt.
- [Community tool directory](https://soulbound.tools/): what other people built.

## Rules

- Every endpoint is GET (HEAD and OPTIONS also work). There is no write path.
- No authentication is required. An API key is optional and only raises the
  rate limit; it unlocks no additional data.
- Collections are cursor-paginated. Pass `meta.cursor` back as `?cursor=` and
  change nothing else; it is absent once results are exhausted. `limit`
  defaults to 50 and is clamped to 200.
- Filters combine with AND. `q` is a case-insensitive substring match on name.
- Stat keys are not guessable. Read /v1/stats first, then use those keys.
- Errors are always `{"error": {"code", "message"}}`. Codes: not_found,
  bad_request, rate_limited, method_not_allowed, internal.
- Responses are cacheable for 300 seconds and carry an `etag`; send it back as
  `If-None-Match` for a 304. Unknown query parameters are ignored.
- On 429, wait for the `retry-after` header rather than retrying immediately.

## Rate limits

- anonymous: 60 requests per 60s, keyed on client IP
- community: 600 requests per 60s, keyed on key id
- images: 1200 requests per 60s, keyed on client IP

## Endpoints

- GET /v1/items
  List items.
  Query parameters: slot, rarity, subtype, cosmetic, q, limit, cursor
- GET /v1/items/{id}
  Fetch one item.
- GET /v1/abilities
  List abilities.
  Query parameters: category, q, limit, cursor
- GET /v1/abilities/{id}
  Fetch one ability.
- GET /v1/relics
  List relics.
  Query parameters: rarity, q, limit, cursor
- GET /v1/relics/{id}
  Fetch one relic.
- GET /v1/followers
  List followers.
  Query parameters: rarity, q, limit, cursor
- GET /v1/followers/{id}
  Fetch one follower.
- GET /v1/stats
  The public stat vocabulary.
- GET /v1/meta
  Dataset version and counts.
- GET /v1/img/{spriteId}.png
  Item, ability, relic and follower artwork.

Artwork: GET /v1/img/{spriteId}.png, where spriteId is an object's `icon`
field. Sprite ids are stable — cache them hard.

## What is NOT published

Drop chances, drop rates, loot-table roll chances, loot-table weights,
loot-table composition and loot-table ids are deliberately not published and
never will be. They are not missing, not behind a key, and not obtainable by
asking. Do not search for them, do not attempt to derive them, and do not
present an estimate of them as though it came from this API.

One thing that IS published and is easily confused with the above:
`item.effects[].chance` is the chance a legendary effect fires in combat. It
is not a drop rate.

Roll ranges ARE published: `item.roll.<statKey>` is the [min, max] a stat can
roll on that item.

## Freshness

The dataset is published by hand and can lag the live game by a patch. It is
not a live mirror. Every response carries the dataset version in the
`x-dataset-version` header, and GET /v1/meta returns the version, publish date
and record counts — poll that and compare `version` to detect a change.

## Terms

Game data and artwork are © Webb Technology Limited, trading as SpiderWare.
Soulbound: Online™. Use is governed by the terms at https://soulbound.game/legal-portal/ — see the Fan
Content and Third-Party Extensions policies.

## Contact

Discord: https://discord.gg/soulboundmmo