{"openapi":"3.1.0","info":{"title":"Soulbound: Online — public game data","version":"2026-08-06.1","summary":"Read-only public data for Soulbound: Online — items, abilities, relics, followers and artwork.","termsOfService":"https://soulbound.game/legal-portal/","license":{"name":"Soulbound: Online usage terms (© Webb Technology Limited, trading as SpiderWare)","url":"https://soulbound.game/legal-portal/"},"description":"Public, read-only, and free. `GET` and `HEAD` only; there is no write path.\n\nRate limits — anonymous: 60 requests / 60s, keyed on client IP; community: 600 requests / 60s, keyed on key id; images: 1200 requests / 60s, keyed on client IP. Every response carries `ratelimit-limit`,\n`ratelimit-remaining` and `ratelimit-reset`; a `429` adds `retry-after`.\n\nAn API key is optional. It raises the limit and lets us tell one consumer from\nanother; it unlocks no extra data. Send it as `Authorization: Bearer <key>`.\n`?key=` also works but is discouraged — a key in a URL leaks into browser\nhistory, `Referer` headers and any log that records request lines.\nAn unknown or revoked key is treated as anonymous, never as an error.\n\nResponses are cacheable for 300 seconds and carry an `etag`; send it back as\n`If-None-Match` for a `304`. Unknown query parameters are ignored.\n\nDrop rates, loot-table weights and loot-table composition are not published\nand never will be. `effects[].chance` is the chance an effect fires in combat.\n\nGame data and artwork are © Webb Technology Limited (trading as SpiderWare);\nSoulbound: Online is a trademark. Use is governed by the terms at\nhttps://soulbound.game/legal-portal/ — see the Fan Content and Third-Party Extensions policies."},"servers":[{"url":"https://api.soulbound.tools"}],"paths":{"/":{"get":{"operationId":"redirect_root","summary":"Redirect to the documentation","tags":["meta"],"description":"302 to /docs.","responses":{"302":{"description":"Redirect to /docs."}}}},"/docs":{"get":{"operationId":"docs_docs","summary":"Human-readable API reference","tags":["meta"],"description":"A self-contained HTML page, rendered from this same spec.","responses":{"200":{"description":"HTML reference.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"openapi_v1_openapijson","summary":"This OpenAPI document","tags":["meta"],"description":"Generated from the Worker's own route table, so it cannot drift from what is served.","responses":{"200":{"description":"This document.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/items":{"get":{"operationId":"collection_v1_items","summary":"List items","tags":["items"],"description":"Every equippable and cosmetic item. Filters combine with AND.","parameters":[{"name":"slot","in":"query","required":false,"description":"Equipment slot, exact match, case-insensitive.","schema":{"type":"string"},"example":"chest"},{"name":"rarity","in":"query","required":false,"description":"Rarity, either numeric (4) or by name (legendary).","schema":{"type":"string"},"example":"legendary"},{"name":"subtype","in":"query","required":false,"description":"Item subtype, exact match, case-insensitive.","schema":{"type":"string"},"example":"sword"},{"name":"cosmetic","in":"query","required":false,"description":"true or false.","schema":{"type":"boolean"},"example":"false"},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on name.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 200 (larger values are clamped).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response's meta.cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"meta":{"$ref":"#/components/schemas/CollectionMeta"}},"required":["data","meta"]}}}},"400":{"description":"Malformed limit, cursor or filter value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/items/{id}":{"get":{"operationId":"single_v1_items_id","summary":"Fetch one item","tags":["items"],"parameters":[{"name":"id","in":"path","required":true,"description":"The resource's public id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Item"}},"required":["data"]}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/abilities":{"get":{"operationId":"collection_v1_abilities","summary":"List abilities","tags":["abilities"],"parameters":[{"name":"category","in":"query","required":false,"description":"Ability category, exact match, case-insensitive.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on name.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 200 (larger values are clamped).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response's meta.cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ability"}},"meta":{"$ref":"#/components/schemas/CollectionMeta"}},"required":["data","meta"]}}}},"400":{"description":"Malformed limit, cursor or filter value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/abilities/{id}":{"get":{"operationId":"single_v1_abilities_id","summary":"Fetch one ability","tags":["abilities"],"parameters":[{"name":"id","in":"path","required":true,"description":"The resource's public id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Ability"}},"required":["data"]}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/relics":{"get":{"operationId":"collection_v1_relics","summary":"List relics","tags":["relics"],"parameters":[{"name":"rarity","in":"query","required":false,"description":"Rarity, either numeric (4) or by name (legendary).","schema":{"type":"string"},"example":"legendary"},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on name.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 200 (larger values are clamped).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response's meta.cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Relic"}},"meta":{"$ref":"#/components/schemas/CollectionMeta"}},"required":["data","meta"]}}}},"400":{"description":"Malformed limit, cursor or filter value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/relics/{id}":{"get":{"operationId":"single_v1_relics_id","summary":"Fetch one relic","tags":["relics"],"parameters":[{"name":"id","in":"path","required":true,"description":"The resource's public id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Relic"}},"required":["data"]}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/followers":{"get":{"operationId":"collection_v1_followers","summary":"List followers","tags":["followers"],"parameters":[{"name":"rarity","in":"query","required":false,"description":"Rarity, either numeric (4) or by name (legendary).","schema":{"type":"string"},"example":"legendary"},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on name.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 200 (larger values are clamped).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"example":50},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous response's meta.cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Follower"}},"meta":{"$ref":"#/components/schemas/CollectionMeta"}},"required":["data","meta"]}}}},"400":{"description":"Malformed limit, cursor or filter value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/followers/{id}":{"get":{"operationId":"single_v1_followers_id","summary":"Fetch one follower","tags":["followers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The resource's public id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Follower"}},"required":["data"]}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stats":{"get":{"operationId":"list_v1_stats","summary":"The public stat vocabulary","tags":["stats"],"description":"Every stat key an item may carry. Small and unpaginated.","responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Stat"}},"meta":{"$ref":"#/components/schemas/CollectionMeta"}},"required":["data","meta"]}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/meta":{"get":{"operationId":"meta_v1_meta","summary":"Dataset version and counts","tags":["meta"],"responses":{"200":{"description":"The resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Meta"}},"required":["data"]}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/img/{spriteId}.png":{"get":{"operationId":"image_v1_img_spriteIdpng","summary":"Item, ability, relic and follower artwork","tags":["meta"],"description":"PNG for the sprite id carried by an object's `icon` field. Served straight from static assets, so it is fast and cheap to fetch in bulk. Sprite ids are stable — cache them hard.","parameters":[{"name":"spriteId","in":"path","required":true,"description":"Sprite id from an object's `icon` field.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]+$"}}],"responses":{"200":{"description":"PNG artwork.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"No sprite with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Item":{"type":"object","description":"An equippable or cosmetic item.","properties":{"id":{"type":"string","description":"Stable public key."},"name":{"type":"string"},"description":{"type":"string","description":"Plain text; colour markup is stripped."},"type":{"type":"string","description":"Slot family."},"slot":{"type":"string"},"subtype":{"type":"string","description":"Absent when the item has none."},"rarity":{"type":"integer","description":"Numeric rarity, low to high."},"rarityName":{"type":"string","description":"e.g. common, rare, legendary."},"cosmetic":{"type":"boolean"},"icon":{"type":"string","description":"Sprite id. Artwork at /v1/img/{icon}.png"},"stats":{"type":"array","items":{"type":"object","properties":{"stat":{"type":"string","description":"Stat key, as listed by /v1/stats."},"value":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}}}},"description":"Stats on this instance."},"roll":{"type":"object","description":"Public min..max roll range per stat, as [min, max].","additionalProperties":{"type":"array","items":{"type":"number"}}},"effects":{"type":"array","description":"Legendary procs. `chance` is the chance the effect fires in combat, in percent — it is not a drop rate.","items":{"type":"object","properties":{"trigger":{"type":"string"},"label":{"type":"string"},"impact":{"type":"string"},"cooldown":{"type":"number"},"chance":{"type":"number"}}}},"requirements":{"type":"array","items":{"type":"object","properties":{"skill":{"type":"string"},"level":{"type":"integer"}}}},"dungeons":{"type":"array","items":{"type":"string"},"description":"Display names of the dungeons this item drops in. Never ids, never rates."}},"required":["id","name","rarity","rarityName"]},"Ability":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"icon":{"type":"string","description":"Sprite id. Artwork at /v1/img/{icon}.png"}},"required":["id","name"]},"Relic":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"unit":{"type":"string"},"prefix":{"type":"string"},"rarity":{"type":"integer"},"rarityName":{"type":"string"},"icon":{"type":"string"},"unique":{"type":"boolean"}},"required":["id","name"]},"Follower":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"rarity":{"type":"integer"},"rarityName":{"type":"string"},"icon":{"type":"string"}},"required":["id","name"]},"Stat":{"type":"object","description":"One entry in the public stat vocabulary.","properties":{"key":{"type":"string","description":"The key used in item.stats[].stat and item.roll."},"name":{"type":"string"},"short":{"type":"string"},"unit":{"type":"string"},"description":{"type":"string"},"cap":{"type":"number","description":"Public balance ceiling, where one is set."}},"required":["key","name"]},"Meta":{"type":"object","properties":{"version":{"type":"string","description":"Dataset version. Also sent as the x-dataset-version header."},"published":{"type":"string","description":"RFC 3339 timestamp."},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"license":{"type":"string"},"docs":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found","bad_request","rate_limited","method_not_allowed","internal"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"CollectionMeta":{"type":"object","properties":{"total":{"type":"integer","description":"Matches for this query across all pages."},"count":{"type":"integer","description":"Items in this page."},"cursor":{"type":"string","description":"Pass as ?cursor= for the next page. Absent when exhausted."}},"required":["total","count"]}},"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Optional. `Authorization: Bearer sbt_live_...`"}}},"security":[{},{"bearerKey":[]}]}