The API follows standard REST conventions — resources have list and detail endpoints, relationships are nested, and actions are POST. All URLs use the base https://versedb.com/api.
See API Endpoint Quick Reference for the full endpoint list. This article covers patterns.
Note
All endpoints require authentication with a Bearer token. See Authentication & API Tokens.
URL Patterns#
| Pattern | Example |
|---|---|
| List | GET /api/publishers |
| Detail | GET /api/series/{id} |
| Relationship (PRO) | GET /api/series/{id}/issues |
| Action | POST /api/follow |
| Search | GET /api/characters?q=batman |
Comic Content (Free)#
Every catalog resource has list and detail endpoints: publishers, titles, series, issues, characters, creators, story arcs, teams, universes, comic shops, and podcasts.
A title is the franchise (e.g., "Amazing Spider-Man"). A series is a specific volume (e.g., "Amazing Spider-Man (2018)"). Issues belong to series.
Some resources have additional discovery endpoints — GET /api/issues/featured, GET /api/characters/featured, GET /api/creators/featured, and GET /api/podcasts/{id}/episodes.
Relationships & Market Data (PRO)#
PRO tokens unlock nested relationship endpoints — /api/series/{id}/issues, /api/series/{id}/creators, /api/series/{id}/characters, /api/issues/{id}/variants, /api/issues/{id}/creators, /api/issues/{id}/characters, /api/teams/{id}/characters, /api/teams/{id}/series, /api/teams/{id}/issues.
Market data endpoints — /api/issues/{id}/market/listings, /market/snapshots, /market/overview — are also PRO-only. Non-PRO users get HTTP 402.
Your Account Data#
Authenticated reads for your own library:
GET /api/user # Your profile
GET /api/user/collections # Your collection
GET /api/user/pull-list # Your pull list
GET /api/user/follows # What you follow
GET /api/user/read-status # Issues you've read
GET /api/user/activity # Your activity feed
GET /api/user/achievements # Your achievements
Mutations#
User lists — full CRUD via /api/lists:
POST /api/lists
PUT /api/lists/{id}
DELETE /api/lists/{id}
POST /api/lists/{id}/items
DELETE /api/lists/{id}/items/{item}
PUT /api/lists/{id}/items/reorder
POST/DELETE /api/lists/{id}/save # save/unsave
POST/DELETE /api/lists/{id}/like # like/unlike
Pull list:
POST /api/pull-list/items
DELETE /api/pull-list/items/{item}
Read status:
POST /api/issues/{id}/read-status
DELETE /api/issues/{id}/read-status
Follows (polymorphic — any followable type):
POST /api/follow
DELETE /api/follow/{type}/{id}
GET /api/follow/{type}/{id}/check
PUT /api/follow/{type}/{id}/preferences
Note
Collection mutations (add/remove/edit items) aren't available through the public API. They're exposed only to the VerseDB mobile app.
Query Parameters#
| Parameter | Description | Default |
|---|---|---|
page |
Page number | 1 |
limit |
Items per page (max 50) | 20 |
q |
Search query | — |
Response Format#
Single-resource responses wrap data:
{ "data": { "id": 123, "name": "Amazing Spider-Man", "start_year": 2018 } }
List responses include pagination metadata:
{
"data": [...],
"meta": { "current_page": 1, "per_page": 20, "total": 500, "last_page": 25 },
"links": { "first": "...", "last": "...", "prev": null, "next": "..." }
}
Web URLs vs API Endpoints#
The website uses slug URLs (/series/123-amazing-spider-man-2018) but the API uses numeric IDs (/api/series/123). Use the list endpoints with q= to look up IDs by name.