Exploring API Endpoints & Structure

Base URL

All API requests start with the base URL:

https://versedb.com/api/v1

Note: The API is versioned (/v1). Future versions may be released as /v2, etc., allowing backward compatibility.

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 (Public)

Publishers

GET /api/v1/publishers              # List all publishers
GET /api/v1/publishers/{id}         # Get publisher details
GET /api/v1/publishers/{id}/series  # Get publisher's series

Titles

GET /api/v1/titles                  # List all titles
GET /api/v1/titles/{id}             # Get title details with all volumes
GET /api/v1/titles/search?q=spider  # Search titles

Series (Volumes)

GET /api/v1/series                  # List all series
GET /api/v1/series/{id}             # Get series details
GET /api/v1/series/{id}/issues      # Get all issues in series
GET /api/v1/series/search?title=batman  # Search series

Note: A "series" refers to a specific volume/run of a title. A "title" represents all volumes across reboots and relaunches.

Issues

GET /api/v1/issues                  # List issues (paginated)
GET /api/v1/issues/{id}             # Get issue details
GET /api/v1/issues/{id}/variants    # Get issue variants
GET /api/v1/series/{id}/issues      # Get issues for a specific series

Story Arcs

GET /api/v1/story-arcs              # List all story arcs
GET /api/v1/story-arcs/{id}         # Get story arc with reading order
GET /api/v1/story-arcs/search?q=civil+war  # Search story arcs

Creators & Characters (Public)

Creators

GET /api/v1/creators                # List creators
GET /api/v1/creators/{id}           # Get creator details
GET /api/v1/creators/{id}/works     # Get creator's work history
GET /api/v1/creators/search?name=stan+lee  # Search creators

Characters

GET /api/v1/characters              # List characters
GET /api/v1/characters/{id}         # Get character details
GET /api/v1/characters/{id}/appearances  # Get character appearances
GET /api/v1/characters/search?name=wolverine  # Search characters

User Profile & Public Data

Public Profiles

GET /api/v1/users/{id}/profile      # Get public profile
GET /api/v1/users/{id}/collection   # Get public collection (if enabled)
GET /api/v1/users/{id}/reviews      # Get user's public reviews
GET /api/v1/users/{id}/lists        # Get user's public reading lists

Note: Only publicly visible data is accessible. Respects user privacy settings.

Personal User Data (Authenticated)

These endpoints require authentication and return data for the authenticated user.

User Profile

GET /api/v1/user                    # Get your profile
PATCH /api/v1/user                  # Update your profile
GET /api/v1/user/stats              # Get your statistics

Following

GET /api/v1/user/follows            # Get titles you follow
POST /api/v1/titles/{id}/follow     # Follow a title
DELETE /api/v1/titles/{id}/follow   # Unfollow a title

Collections (Authenticated)

Manage your comic collection:

GET /api/v1/user/collection         # Get your entire collection
GET /api/v1/user/collection/{id}    # Get specific collection item

POST /api/v1/user/collection        # Add issue to collection
PUT /api/v1/user/collection/{id}    # Update collection item
PATCH /api/v1/user/collection/{id}  # Partial update
DELETE /api/v1/user/collection/{id} # Remove from collection

POST /api/v1/user/collection/bulk   # Bulk add issues
DELETE /api/v1/user/collection/bulk # Bulk remove issues

GET /api/v1/user/collection/stats   # Get collection statistics

Example: Add to Collection

POST /api/v1/user/collection
{
  "issue_id": 12345,
  "condition": "NM",
  "purchase_price": 3.99,
  "notes": "First appearance"
}

Wishlists (Authenticated)

Track issues you want to acquire:

GET /api/v1/user/wishlist           # Get your wishlist
GET /api/v1/user/wishlist/{id}      # Get specific wishlist item

POST /api/v1/user/wishlist          # Add to wishlist
PUT /api/v1/user/wishlist/{id}      # Update wishlist item
DELETE /api/v1/user/wishlist/{id}   # Remove from wishlist

POST /api/v1/user/wishlist/bulk     # Bulk add
DELETE /api/v1/user/wishlist/bulk   # Bulk remove

Pull Lists (Authenticated)

Track upcoming releases you want to purchase:

GET /api/v1/user/pulllist           # Get your pull list
GET /api/v1/user/pulllist/upcoming  # Get upcoming releases

POST /api/v1/user/pulllist          # Add series to pull list
DELETE /api/v1/user/pulllist/{id}   # Remove series from pull list

POST /api/v1/user/pulllist/{id}/purchased  # Mark issue as purchased

Read Status (Authenticated)

Track your reading progress:

GET /api/v1/user/read               # Get all read issues
GET /api/v1/user/read/{issue_id}    # Get read status for issue

POST /api/v1/user/read              # Mark issue as read
DELETE /api/v1/user/read/{issue_id} # Mark as unread

POST /api/v1/user/read/bulk         # Bulk mark as read

GET /api/v1/user/read/stats         # Get reading statistics
GET /api/v1/series/{id}/progress    # Get reading progress for series

Reviews (Public Read, Authenticated Write)

GET /api/v1/issues/{id}/reviews     # Get reviews for issue
GET /api/v1/reviews/{id}            # Get specific review

POST /api/v1/issues/{id}/reviews    # Write review (auth required)
PUT /api/v1/reviews/{id}            # Update your review
DELETE /api/v1/reviews/{id}         # Delete your review

Query Parameters

Most list endpoints support filtering and pagination:

Common Parameters

• page - Page number (default: 1)
• per_page - Items per page (default: 20, max: 100)
• sort - Sort field (e.g., name, release_date)
• order - Sort order (asc or desc)

Filtering Examples

GET /api/v1/series?publisher_id=1&year=2018
GET /api/v1/issues?series_id=123&release_date_from=2020-01-01
GET /api/v1/characters?universe_id=2&sort=name&order=asc

Response Format

All responses use JSON format:

Success Response

{
  "data": {
    "id": 123,
    "name": "Amazing Spider-Man",
    "start_year": 2018
  },
  "meta": {
    "timestamp": "2025-04-12T15:30:00Z"
  }
}

List Response (Paginated)

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

Web URLs vs API Endpoints

The website uses SEO-friendly slugs, but the API uses numeric IDs:

Converting: Use the API's search endpoints to find IDs from names, or extract IDs from web URLs.

Nested Resources

Some endpoints require multiple IDs in the path:

GET /api/v1/series/{series_id}/issues/{issue_id}
PUT /api/v1/user/collection/{collection_id}
DELETE /api/v1/user/wishlist/{wishlist_id}

Tips & Best Practices

1. Use specific endpoints when available instead of filtering lists
2. Request only needed fields using ?fields=id,name,start_year
3. Leverage pagination for large datasets
4. Cache public data (publishers, series) as it changes infrequently
5. Use bulk endpoints for multiple operations
6. Check the interactive docs at /api/docs for latest endpoints

Next: Learn best practices in "Best Practices for Using the VerseDB API"