API overview
SoulsAPI is read-only. Data routes require an API key and enforce daily rate limits.
Authentication
Send your API key on every GET /v1/{gameId}/... request:
curl -s -H "X-API-Key: YOUR_KEY" \ "https://www.souls-api.com/v1/bloodborne/bosses?page_size=1"Authorization: Bearer YOUR_KEY is also accepted. /v1/health, /openapi.json, and /docs do not require a key.
Test API keys are not self-service. Request one by contacting the maintainer on Discord: omaretot (user id 592473249628291082). Include your email and how you plan to use the API. Keys are tied to an owner_email for fair-use limits.
All curl examples in these docs use X-API-Key: YOUR_API_KEY — replace YOUR_API_KEY with the value you receive.
Rate limits
| Plan | Per key / day | Per email / day |
|---|---|---|
| Free | 100 | 150 |
| Standard | 1,000 | 1,500 |
| Internal | 50,000 | 50,000 |
Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. GET .../search counts as 5 units on free/standard plans.
Conventions
- JSON responses use UTF-8.
- List endpoints return
{ data, meta }with pagination metadata. - Game data is namespaced:
/v1/{gameId}/...(for examplebloodborne). Shared route modules are mounted per title inapps/api/src/games/<gameId>/.