Exploring API Endpoints & Structure

Base URL

All API requests start with the base URL:

https://versedb.com/api

URL Structure & Patterns

The API follows RESTful conventions with predictable URL patterns:

HTTP Methods

The API uses standard HTTP methods:

• GET - Retrieve data (read-only)
• POST - Create new resources
• PUT/PATCH - Update existing resources
• DELETE - Remove resources

Comic Content Endpoints (All Users)

Publishers

GET /api/publishers              # List all publishers
GET /api/publishers/{id}         # Get publisher details

Titles

GET /api/titles                  # List all titles
GET /api/titles/{id}             # Get title details

Series (Volumes)

GET /api/series                  # List all series
GET /api/series/{id}             # Get series details

Issues

GET /api/issues                  # List issues (paginated)
GET /api/issues/{id}             # Get issue details
GET /api/issues/featured         # Get featured issues

Story Arcs

GET /api/story-arcs              # List all story arcs
GET /api/story-arcs/{id}         # Get story arc details

Characters

GET /api/characters              # List characters
GET /api/characters/{id}         # Get character details
GET /api/characters/featured     # Get featured characters

Creators

GET /api/creators                # List creators
GET /api/creators/{id}           # Get creator details
GET /api/creators/featured       # Get featured creators

Teams

GET /api/teams                   # List teams
GET /api/teams/{id}              # Get team details

Universes

GET /api/universes               # List universes
GET /api/universes/{id}          # Get universe details

Comic Shops

GET /api/shops                   # List shops
GET /api/shops/{id}              # Get shop details

Podcasts

GET /api/podcasts                # List podcasts
GET /api/podcasts/{id}           # Get podcast details
GET /api/podcasts/{id}/episodes  # Get podcast episodes

Relationship Endpoints (PRO Only)

Series Relationships

GET /api/series/{id}/issues      # Get all issues in series
GET /api/series/{id}/creators    # Get creators for series
GET /api/series/{id}/characters  # Get characters in series

Issue Relationships

GET /api/issues/{id}/creators    # Get creators for issue
GET /api/issues/{id}/characters  # Get characters in issue
GET /api/issues/{id}/variants    # Get issue variants

Team Relationships

GET /api/teams/{id}/characters   # Get team members
GET /api/teams/{id}/series       # Get team's series
GET /api/teams/{id}/issues       # Get team's issues

Market Data (PRO Only)

GET /api/issues/{id}/market/listings   # Live marketplace listings
GET /api/issues/{id}/market/snapshots  # Price history
GET /api/issues/{id}/market/overview   # Estimated values

Personal User Data (Authenticated)

These endpoints return data for the authenticated user.

User Profile

GET /api/user                    # Get your profile
GET /api/user/collections        # Get your collections
GET /api/user/lists              # Get your user lists
GET /api/user/pull-list          # Get your pull list
GET /api/user/follows            # Get titles you follow
GET /api/user/read-status        # Get your read issues

Collections (Authenticated)

Manage your comic collection:

GET /api/user/collections        # Get your collections

POST /api/collections            # Create new collection
PUT /api/collections/{id}        # Update collection
DELETE /api/collections/{id}     # Delete collection

POST /api/collections/{id}/items           # Add item to collection
DELETE /api/collections/{id}/items/{item}  # Remove item from collection

User Lists (Authenticated)

Manage your lists including your default wishlist and custom lists:

GET /api/user/lists              # Get your lists

POST /api/lists                  # Create list
PUT /api/lists/{id}              # Update list
DELETE /api/lists/{id}           # Delete list (not wishlist)

POST /api/lists/{id}/items           # Add to list
DELETE /api/lists/{id}/items/{item}  # Remove from list

Pull Lists (Authenticated)

Track series you want to follow:

GET /api/user/pull-list          # Get your pull list
POST /api/pull-list/items        # Add series to pull list
DELETE /api/pull-list/items/{id} # Remove from pull list

Read Status (Authenticated)

Track your reading progress:

GET /api/user/read-status            # Get all read issues
POST /api/issues/{id}/read-status    # Mark issue as read
DELETE /api/issues/{id}/read-status  # Mark as unread

Following (Authenticated)

Follow titles, characters, podcasts:

POST /api/follow                     # Follow something
DELETE /api/follow/{type}/{id}       # Unfollow
GET /api/follow/{type}/{id}/check    # Check if following

Query Parameters

Most list endpoints support filtering and pagination:

Filtering Examples

GET /api/series?q=spider-man
GET /api/issues?limit=50&page=2
GET /api/characters?q=wolverine

Response Format

All responses use JSON format:

Success Response

{
  "data": {
    "id": 123,
    "name": "Amazing Spider-Man",
    "start_year": 2018
  }
}

List Response (Paginated)

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 500,
    "last_page": 25
  },
  "links": {
    "first": "/api/series?page=1",
    "last": "/api/series?page=25",
    "prev": null,
    "next": "/api/series?page=2"
  }
}

PRO Required Response (402)

{
  "message": "PRO subscription required",
  "error": "pro_required",
  "upgrade_url": "https://versedb.com/subscription"
}

Web URLs vs API Endpoints

Use the API's search endpoints to find IDs from names.