Skip to content
VerseDB

Issues

Endpoints for browsing and searching comic book issues.

An issue is a single publication in a series (e.g., "Amazing Spider-Man #1").

Get issue variants.

GET/api/v1/issues/{issue_id}/variants
Requires a token

Returns all variant covers for a specific issue.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Query parameters

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes.

Example: "ja,ko"

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataarray of objectsrequired
data[].idintegerrequired

Example: 901

data[].issue_idinteger or nullrequired

Example: 5432

data[].variant_namestring or nullrequired

Example: "Cover B"

data[].cover_urlstring or nullrequired

Example: "https://...-cover_lg.webp"

data[].imagesobject or nullrequired
data[].images.thumbstring

Example: "https://...-thumb.webp"

data[].images.cover_smstring

Example: "https://...-cover_sm.webp"

data[].images.cover_mdstring

Example: "https://...-cover_md.webp"

data[].images.cover_lgstring

Example: "https://...-cover_lg.webp"

data[].variant_typestring or nullrequired

Example: "standard"

data[].ratiostring or nullrequired

Example: "1:25"

data[].pricestring or nullrequired

Example: "4.99"

data[].currency_codestring or nullrequired

Example: "USD"

data[].formatted_pricestring or nullrequired

Example: "$4.99"

data[].eanstring or nullrequired

Example: "75960609999300111"

data[].release_datestring or nullrequired

This edition's own on-sale date (YYYY-MM-DD), for a later printing or an exclusive that ships apart from its issue. Null when it ships with the issue: use the issue's release_date.

Example: "2025-04-09"

data[].is_nsfwbooleanrequired
data[].creatorsarray of objectsrequired
data[].creators[].idintegerrequired

Example: 81

data[].creators[].namestring or nullrequired

Example: "Fiona Staples"

data[].creators[].rolestringrequired

Example: "Cover Artist"

data[].variant_name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues/5432/variants' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 901,
      "issue_id": 5432,
      "variant_name": "Cover B",
      "cover_url": "https://...-cover_lg.webp",
      "images": {
        "thumb": "https://...-thumb.webp",
        "cover_sm": "https://...-cover_sm.webp",
        "cover_md": "https://...-cover_md.webp",
        "cover_lg": "https://...-cover_lg.webp"
      },
      "variant_type": "standard",
      "ratio": "1:25",
      "price": "4.99",
      "currency_code": "USD",
      "formatted_price": "$4.99",
      "ean": "75960609999300111",
      "release_date": "2025-04-09",
      "creators": [
        {
          "id": 81,
          "name": "Fiona Staples",
          "role": "Cover Artist"
        }
      ],
      "variant_name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      }
    }
  ]
}

Get issue details.

GET/api/v1/issues/{issue_id}
Requires a token

Returns a single issue with full details including series, title, publishers, creators, characters, teams, and story arcs.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Query parameters

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes.

Example: "ja,ko"

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataobjectrequired
data.idintegerrequired

Example: 5432

data.slugstring or nullrequired

Example: "amazing-spider-man-1"

data.series_idinteger or nullrequired

Example: 123

data.issue_numberstring or nullrequired

Example: "1"

data.namestring or nullrequired

Example: "The Chameleon Strikes!"

data.solicitationstring or nullrequired

Example: "The publisher's solicitation text."

data.release_datestring or nullrequired

Example: "2018-07-11"

data.foc_datestring or nullrequired

Example: "2018-06-18"

data.cover_datestring or nullrequired

Example: "2018-09-01"

data.is_unreleasedbooleanrequired
data.cover_urlstring or nullrequired

Example: "https://...-cover_lg.webp"

data.imagesobject or nullrequired
data.images.thumbstring

Example: "https://...-thumb.webp"

data.images.cover_smstring

Example: "https://...-cover_sm.webp"

data.images.cover_mdstring

Example: "https://...-cover_md.webp"

data.images.cover_lgstring

Example: "https://...-cover_lg.webp"

data.is_reprintboolean or nullrequired
data.content_rating_labelstring or nullrequired

Example: "Teen"

data.min_ageinteger or nullrequired

Example: 13

data.is_nsfwboolean or nullrequired
data.page_countinteger or nullrequired

Example: 32

data.pricestring or nullrequired

Example: "4.99"

data.currency_codestring or nullrequired

Example: "USD"

data.formatted_pricestring or nullrequired

Example: "USD $4.99"

data.isbnstring or nullrequired

Example: "9781302912345"

data.upcstring or nullrequired

Example: "75960608936700111"

data.lunar_codestring or nullrequired

Example: "0518MA0001"

data.universal_codestring or nullrequired

Example: "UC1"

data.diamond_codestring or nullrequired

Example: "MAY180001"

data.eanstring or nullrequired

Example: "9781302912345"

data.issnstring or nullrequired

Example: "1234-5678"

data.is_anthologyboolean or nullrequired
data.is_tie_inbooleanrequired
data.adapted_fromstring or nullrequired

Example: "anime"

data.print_runinteger or nullrequired

Example: 12000

data.locationsstring or nullrequired

Example: "Gotham"

data.skustring or nullrequired

Example: "SKU-1"

data.variant_countintegerrequired

Example: 4

data.reads_countintegerrequired

Example: 120

data.average_ratingnumber

Example: 4.5

data.review_countinteger

Example: 12

data.titleobject
data.title.idintegerrequired

Example: 1

data.title.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.title.slugstring or nullrequired

Example: "the-amazing-spider-man"

data.seriesobject or nullrequired
data.series.idintegerrequired

Example: 123

data.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.series.slugstring or nullrequired

Example: "the-amazing-spider-man-2018"

data.series.start_yearinteger or nullrequired

Example: 2018

data.series.end_yearinteger or nullrequired

Example: 2022

data.series.volume_numberinteger or nullrequired

Example: 5

data.series.statusstring or nullrequired

Example: "Ongoing"

data.series.publication_typestring or nullrequired

Example: "regular_series"

data.series.cached_issues_countinteger or nullrequired

Example: 93

data.series.mediumstringrequired

Example: "comic"

data.series.formatstring or nullrequired

Example: "Standard"

data.series.content_rating_labelstring or nullrequired

Example: "Teen"

data.series.min_ageinteger or nullrequired

Example: 13

data.series.is_nsfwbooleanrequired
data.series.original_languagestring or nullrequired

Example: "en"

data.series.languagestring or nullrequired

Example: "en"

data.series.genresarray of objectsrequired
data.series.genres[].idintegerrequired

Example: 3

data.series.genres[].namestring or nullrequired

Example: "Superhero"

data.series.genres[].slugnull or nullrequired
data.series.aliasesarray of stringsrequired
data.series.imprintobject or nullrequired
data.series.imprint.idintegerrequired

Example: 7

data.series.imprint.namestring or nullrequired

Example: "Marvel Knights"

data.series.foreign_edition_ofarray of objectsrequired
data.series.foreign_edition_of[].idintegerrequired

Example: 1

data.series.foreign_edition_of[].namestringrequired
data.series.foreign_edition_of[].slugstring or nullrequired

Example: "slug"

data.series.foreign_edition_of[].languagestring or nullrequired
data.series.foreign_editionsarray of objectsrequired
data.series.foreign_editions[].idintegerrequired

Example: 1

data.series.foreign_editions[].namestringrequired
data.series.foreign_editions[].slugstring or nullrequired

Example: "slug"

data.series.foreign_editions[].languagestring or nullrequired
data.publisherobject or null
data.publisher.idintegerrequired

Example: 1

data.publisher.namestring or nullrequired

Example: "Marvel"

data.publisher.slugstring or nullrequired

Example: "marvel"

data.imprintobject
data.imprint.idintegerrequired

Example: 7

data.imprint.namestring or nullrequired

Example: "Marvel Knights"

data.awardsarray of objectsrequired
data.awards[].idintegerrequired

Example: 3

data.awards[].namestring or nullrequired

Example: "Eisner Award"

data.awards[].categorystring or nullrequired

Example: "Best Single Issue"

data.awards[].yearinteger or nullrequired

Example: 2019

data.creatorsarray of objectsrequired
data.creators[].idintegerrequired

Example: 81

data.creators[].namestring or nullrequired

Example: "Nick Spencer"

data.creators[].slugstring or nullrequired

Example: "nick-spencer"

data.creators[].photo_urlstring or nullrequired

Example: "https://...-profile_md.webp"

data.creators[].imagesobject or nullrequired
data.creators[].images.tile_smstring

Example: "https://...-tile_sm.webp"

data.creators[].images.profile_mdstring

Example: "https://...-profile_md.webp"

data.creators[].images.full_lgstring

Example: "https://...-full_lg.webp"

data.creators[].rolestringrequired

Example: "Writer"

data.creators[].sort_orderinteger or nullrequired

Example: 1

data.charactersarray of objectsrequired
data.characters[].idintegerrequired

Example: 1

data.characters[].namestring or nullrequired

Example: "Spider-Man"

data.characters[].slugstring or nullrequired

Example: "spider-man"

data.characters[].real_namestring or nullrequired

Example: "Peter Parker"

data.characters[].image_urlstring or nullrequired

Example: "https://...-profile_md.webp"

data.characters[].imagesobject or nullrequired
data.characters[].images.tile_smstring

Example: "https://...-tile_sm.webp"

data.characters[].images.profile_mdstring

Example: "https://...-profile_md.webp"

data.characters[].images.full_lgstring

Example: "https://...-full_lg.webp"

data.characters[].sort_orderinteger or nullrequired

Example: 1

data.teamsarray of objectsrequired
data.teams[].idintegerrequired

Example: 1

data.teams[].namestring or nullrequired

Example: "The Avengers"

data.teams[].slugstring or nullrequired

Example: "avengers"

data.teams[].headquartersstring or nullrequired

Example: "Avengers Tower"

data.teams[].image_urlstring or nullrequired

Example: "https://...-tile_sm.webp"

data.teams[].imagesobject or nullrequired
data.teams[].images.tile_smstring

Example: "https://...-tile_sm.webp"

data.teams[].images.profile_mdstring

Example: "https://...-profile_md.webp"

data.teams[].images.full_lgstring

Example: "https://...-full_lg.webp"

data.teams[].sort_orderinteger or nullrequired

Example: 1

data.story_arcsarray of objectsrequired
data.story_arcs[].idintegerrequired

Example: 24

data.story_arcs[].namestring or nullrequired

Example: "Civil War"

data.story_arcs[].slugstring or nullrequired

Example: "civil-war"

data.story_arcs[].image_urlstring or nullrequired

Example: "https://...-cover_md.webp"

data.story_arcs[].imagesobject or nullrequired
data.story_arcs[].images.cover_smstring

Example: "https://...-cover_sm.webp"

data.story_arcs[].images.cover_mdstring

Example: "https://...-cover_md.webp"

data.story_arcs[].images.cover_lgstring

Example: "https://...-cover_lg.webp"

data.story_arcs[].sort_orderinteger or nullrequired

Example: 1

data.universesarray of objectsrequired
data.universes[].idintegerrequired

Example: 1

data.universes[].namestring or nullrequired

Example: "Earth-616"

data.comic_eventsarray of objectsrequired
data.comic_events[].idintegerrequired

Example: 1

data.comic_events[].namestring or nullrequired

Example: "San Diego Comic-Con"

data.comic_events[].slugstring or nullrequired

Example: "sdcc"

data.comic_events[].typestring or nullrequired

Example: "exclusive"

data.comic_events[].notesstring or nullrequired

Example: "Signed"

data.comic_events[].display_orderinteger or nullrequired

Example: 1

data.key_issue_reasonsarray of objectsrequired
data.key_issue_reasons[].idintegerrequired

Example: 1

data.key_issue_reasons[].namestring or nullrequired

Example: "1st Appearance"

data.key_issue_reasons[].categorystringrequired

Example: "appearance"

data.key_issue_reasons[].notesstring or nullrequired

Example: "Cameo"

data.availabilitiesarray of objectsrequired
data.availabilities[].idinteger or nullrequired

Example: 10

data.availabilities[].providerstringrequired

Example: "midtown_comics"

data.availabilities[].provider_labelstringrequired

Example: "Midtown Comics"

data.availabilities[].kindstringrequired

buy, read or watch.

Example: "buy"

data.availabilities[].store_namestring or nullrequired

Example: "Midtown Comics"

data.availabilities[].custom_namestring or nullrequired

Example: "Signed edition"

data.availabilities[].display_namestringrequired

Example: "Midtown Comics"

data.availabilities[].store_logostring or nullrequired

Example: "/images/brands/midtown.png"

data.availabilities[].urlstringrequired

Example: "https://www.midtowncomics.com/..."

data.availabilities[].external_idstring or nullrequired

Example: "12345"

data.availabilities[].pricenumber or nullrequired

Example: 19.99

data.availabilities[].formatted_pricestring or nullrequired

Example: "$19.99"

data.availabilities[].currencystring or nullrequired

Example: "USD"

data.availabilities[].is_digitalboolean or nullrequired
data.availabilities[].is_affiliatebooleanrequired
data.availabilities[].is_synthesizedbooleanrequired
data.availabilities[].verified_atstring or nullrequired

Example: "2026-01-01T00:00:00+00:00"

data.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
404

Not Found

messagestringrequired

Example: "No query results for model [App\\Models\\Issue] 5432"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\Issue] 5432"
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues/5432' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "id": 5432,
    "slug": "amazing-spider-man-1",
    "series_id": 123,
    "issue_number": "1",
    "name": "The Chameleon Strikes!",
    "solicitation": "The publisher's solicitation text.",
    "release_date": "2018-07-11",
    "foc_date": "2018-06-18",
    "cover_date": "2018-09-01",
    "cover_url": "https://...-cover_lg.webp",
    "images": {
      "thumb": "https://...-thumb.webp",
      "cover_sm": "https://...-cover_sm.webp",
      "cover_md": "https://...-cover_md.webp",
      "cover_lg": "https://...-cover_lg.webp"
    },
    "content_rating_label": "Teen",
    "min_age": 13,
    "page_count": 32,
    "price": "4.99",
    "currency_code": "USD",
    "formatted_price": "USD $4.99",
    "isbn": "9781302912345",
    "upc": "75960608936700111",
    "lunar_code": "0518MA0001",
    "universal_code": "UC1",
    "diamond_code": "MAY180001",
    "ean": "9781302912345",
    "issn": "1234-5678",
    "adapted_from": "anime",
    "print_run": 12000,
    "locations": "Gotham",
    "sku": "SKU-1",
    "variant_count": 4,
    "reads_count": 120,
    "average_rating": 4.5,
    "review_count": 12,
    "title": {
      "id": 1,
      "name": "The Amazing Spider-Man",
      "slug": "the-amazing-spider-man"
    },
    "series": {
      "id": 123,
      "name": "The Amazing Spider-Man",
      "slug": "the-amazing-spider-man-2018",
      "start_year": 2018,
      "end_year": 2022,
      "volume_number": 5,
      "status": "Ongoing",
      "publication_type": "regular_series",
      "cached_issues_count": 93,
      "medium": "comic",
      "format": "Standard",
      "content_rating_label": "Teen",
      "min_age": 13,
      "original_language": "en",
      "language": "en",
      "genres": [
        {
          "id": 3,
          "name": "Superhero"
        }
      ],
      "imprint": {
        "id": 7,
        "name": "Marvel Knights"
      },
      "foreign_edition_of": [
        {
          "id": 1,
          "slug": "slug"
        }
      ],
      "foreign_editions": [
        {
          "id": 1,
          "slug": "slug"
        }
      ]
    },
    "publisher": {
      "id": 1,
      "name": "Marvel",
      "slug": "marvel"
    },
    "imprint": {
      "id": 7,
      "name": "Marvel Knights"
    },
    "awards": [
      {
        "id": 3,
        "name": "Eisner Award",
        "category": "Best Single Issue",
        "year": 2019
      }
    ],
    "creators": [
      {
        "id": 81,
        "name": "Nick Spencer",
        "slug": "nick-spencer",
        "photo_url": "https://...-profile_md.webp",
        "images": {
          "tile_sm": "https://...-tile_sm.webp",
          "profile_md": "https://...-profile_md.webp",
          "full_lg": "https://...-full_lg.webp"
        },
        "role": "Writer",
        "sort_order": 1
      }
    ],
    "characters": [
      {
        "id": 1,
        "name": "Spider-Man",
        "slug": "spider-man",
        "real_name": "Peter Parker",
        "image_url": "https://...-profile_md.webp",
        "images": {
          "tile_sm": "https://...-tile_sm.webp",
          "profile_md": "https://...-profile_md.webp",
          "full_lg": "https://...-full_lg.webp"
        },
        "sort_order": 1
      }
    ],
    "teams": [
      {
        "id": 1,
        "name": "The Avengers",
        "slug": "avengers",
        "headquarters": "Avengers Tower",
        "image_url": "https://...-tile_sm.webp",
        "images": {
          "tile_sm": "https://...-tile_sm.webp",
          "profile_md": "https://...-profile_md.webp",
          "full_lg": "https://...-full_lg.webp"
        },
        "sort_order": 1
      }
    ],
    "story_arcs": [
      {
        "id": 24,
        "name": "Civil War",
        "slug": "civil-war",
        "image_url": "https://...-cover_md.webp",
        "images": {
          "cover_sm": "https://...-cover_sm.webp",
          "cover_md": "https://...-cover_md.webp",
          "cover_lg": "https://...-cover_lg.webp"
        },
        "sort_order": 1
      }
    ],
    "universes": [
      {
        "id": 1,
        "name": "Earth-616"
      }
    ],
    "comic_events": [
      {
        "id": 1,
        "name": "San Diego Comic-Con",
        "slug": "sdcc",
        "type": "exclusive",
        "notes": "Signed",
        "display_order": 1
      }
    ],
    "key_issue_reasons": [
      {
        "id": 1,
        "name": "1st Appearance",
        "category": "appearance",
        "notes": "Cameo"
      }
    ],
    "availabilities": [
      {
        "id": 10,
        "provider": "midtown_comics",
        "provider_label": "Midtown Comics",
        "kind": "buy",
        "store_name": "Midtown Comics",
        "custom_name": "Signed edition",
        "display_name": "Midtown Comics",
        "store_logo": "/images/brands/midtown.png",
        "url": "https://www.midtowncomics.com/...",
        "external_id": "12345",
        "price": 19.99,
        "formatted_price": "$19.99",
        "currency": "USD",
        "verified_at": "2026-01-01T00:00:00+00:00"
      }
    ],
    "name_i18n": {
      "ja": {
        "value": "講談社",
        "reading": "こうだんしゃ",
        "source": "madb"
      }
    }
  }
}

List issues.

GET/api/v1/issues
Requires a token

Returns paginated issues with optional search, filtering, and sorting.

Query parameters

qstring

Search by issue name.

Example: "spider"

series_idinteger

Filter by series ID.

Example: 123

publisher_idinteger

Filter by publisher ID (via series relationship).

Example: 1

release_date_fromstring

Filter by release date (from).

Example: "2024-01-01"

release_date_tostring

Filter by release date (to).

Example: "2024-12-31"

publisher_idsstring

Comma-separated publisher IDs; matches issues from any of them.

Example: "1,2"

series_idsstring

Comma-separated series IDs; matches issues in any of them.

Example: "123,456"

title_idsstring

Comma-separated title (franchise) IDs; matches issues whose series belongs to any of them.

Example: "45"

character_idsstring

Comma-separated character IDs, up to 10; an issue must feature every one.

Example: "1,2"

creator_idsstring

Comma-separated creator IDs, up to 10; an issue must credit every one.

Example: "81"

creator_role_idsstring

Comma-separated creator role IDs; with creator_ids, each creator must be credited in one of these roles.

Example: "1,2"

team_idsstring

Comma-separated team IDs, up to 10; an issue must feature every one.

Example: "5"

genre_idsstring

Comma-separated genre IDs; matches issues whose series carries any of them.

Example: "3"

languagesstring

Comma-separated series language codes (en, ja, fr, ...).

Example: "en,ja"

mediumstring

Series medium (comic, manga, manhwa, manhua, bande_dessinee, magazine).

Example: "manga"

key_issues_onlyboolean

Only return issues with at least one key issue reason.

Example: true

hide_unreleasedboolean

Leave out issues whose release date is in the future.

Example: true

includestring

Comma-separated relationships to include (series).

Example: "series"

sortstring

Sort field (issue_number, release_date, name).

Example: "release_date"

directionstring

Sort direction (asc, desc).

Example: "desc"

limitinteger

Results per page (max 100).

Example: 20

pageinteger

Page number; meta.last_page says where the list ends.

Example: 1

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataarray of objectsrequired
data[].idintegerrequired

Example: 5432

data[].slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].series_idinteger or nullrequired

Example: 123

data[].issue_numberstring or nullrequired

Example: "1"

data[].namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].cover_datestring or nullrequired

Example: "2018-09-01"

data[].release_datestring or nullrequired

Example: "2018-07-11"

data[].foc_datestring or nullrequired

Example: "2018-06-18"

data[].is_unreleasedbooleanrequired
data[].cover_urlstring or nullrequired

Example: "https://...-cover_lg.webp"

data[].imagesobject or nullrequired
data[].images.thumbstring

Example: "https://...-thumb.webp"

data[].images.cover_smstring

Example: "https://...-cover_sm.webp"

data[].images.cover_mdstring

Example: "https://...-cover_md.webp"

data[].images.cover_lgstring

Example: "https://...-cover_lg.webp"

data[].is_reprintbooleanrequired
data[].content_rating_labelstring or nullrequired

Example: "Teen"

data[].min_ageinteger or nullrequired

Example: 13

data[].is_nsfwbooleanrequired
data[].average_ratingnumber or nullrequired

Example: 4.5

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].seriesobject or null
data[].series.idintegerrequired

Example: 123

data[].series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].series.slugstring or nullrequired

Example: "the-amazing-spider-man-2018"

data[].series.start_yearinteger or nullrequired

Example: 2018

data[].series.end_yearinteger or nullrequired

Example: 2022

data[].series.volume_numberinteger or nullrequired

Example: 5

data[].series.publication_typestring or nullrequired

Example: "regular_series"

data[].series.formatstring or nullrequired

Example: "Standard"

data[].series.cached_issues_countinteger or nullrequired

Example: 93

data[].series.cover_urlstring or nullrequired

Example: "https://...-cover_lg.webp"

data[].series.imagesobject or nullrequired
data[].series.images.cover_smstring

Example: "https://...-cover_sm.webp"

data[].series.images.cover_mdstring

Example: "https://...-cover_md.webp"

data[].series.images.cover_lgstring

Example: "https://...-cover_lg.webp"

data[].series.publisher_namestring or nullrequired

Example: "Marvel"

linksobjectrequired
links.firststringrequired
links.laststringrequired
links.prevstring or nullrequired
links.nextstring or nullrequired
metaobjectrequired
meta.current_pageintegerrequired

Example: 1

meta.frominteger or nullrequired

Example: 1

meta.last_pageintegerrequired

Example: 25

meta.linksarray of objectsrequired
meta.links[].urlstring or nullrequired
meta.links[].labelstringrequired
meta.links[].pageinteger or null
meta.links[].activebooleanrequired
meta.pathstringrequired
meta.per_pageintegerrequired

Example: 20

meta.tointeger or nullrequired

Example: 20

meta.totalintegerrequired

Example: 500

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 5432,
      "slug": "amazing-spider-man-1",
      "series_id": 123,
      "issue_number": "1",
      "name": "The Chameleon Strikes!",
      "cover_date": "2018-09-01",
      "release_date": "2018-07-11",
      "foc_date": "2018-06-18",
      "cover_url": "https://...-cover_lg.webp",
      "images": {
        "thumb": "https://...-thumb.webp",
        "cover_sm": "https://...-cover_sm.webp",
        "cover_md": "https://...-cover_md.webp",
        "cover_lg": "https://...-cover_lg.webp"
      },
      "content_rating_label": "Teen",
      "min_age": 13,
      "average_rating": 4.5,
      "name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      },
      "series": {
        "id": 123,
        "name": "The Amazing Spider-Man",
        "slug": "the-amazing-spider-man-2018",
        "start_year": 2018,
        "end_year": 2022,
        "volume_number": 5,
        "publication_type": "regular_series",
        "format": "Standard",
        "cached_issues_count": 93,
        "cover_url": "https://...-cover_lg.webp",
        "images": {
          "cover_sm": "https://...-cover_sm.webp",
          "cover_md": "https://...-cover_md.webp",
          "cover_lg": "https://...-cover_lg.webp"
        },
        "publisher_name": "Marvel"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

Get variant details.

GET/api/v1/issues/{issue_id}/variants/{variant_id}
Requires a token

Returns a specific variant cover with full details.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

variant_idintegerrequired

The variant ID.

Example: 9001

Query parameters

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes.

Example: "ja,ko"

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataobjectrequired
data.idintegerrequired

Example: 901

data.issue_idinteger or nullrequired

Example: 5432

data.variant_namestring or nullrequired

Example: "Cover B"

data.cover_urlstring or nullrequired

Example: "https://...-cover_lg.webp"

data.imagesobject or nullrequired
data.images.thumbstring

Example: "https://...-thumb.webp"

data.images.cover_smstring

Example: "https://...-cover_sm.webp"

data.images.cover_mdstring

Example: "https://...-cover_md.webp"

data.images.cover_lgstring

Example: "https://...-cover_lg.webp"

data.variant_typestring or nullrequired

Example: "standard"

data.ratiostring or nullrequired

Example: "1:25"

data.pricestring or nullrequired

Example: "4.99"

data.currency_codestring or nullrequired

Example: "USD"

data.formatted_pricestring or nullrequired

Example: "$4.99"

data.eanstring or nullrequired

Example: "75960609999300111"

data.release_datestring or nullrequired

This edition's own on-sale date (YYYY-MM-DD), for a later printing or an exclusive that ships apart from its issue. Null when it ships with the issue: use the issue's release_date.

Example: "2025-04-09"

data.creatorsarray of objectsrequired
data.creators[].idintegerrequired

Example: 101

data.creators[].namestring or nullrequired

Example: "J. Scott Campbell"

data.creators[].slugstring or nullrequired

Example: "j-scott-campbell"

data.creators[].photo_urlstring or nullrequired

Example: "https://...-profile_md.webp"

data.creators[].rolestringrequired

Example: "Cover Artist"

data.creators[].is_uncreditedbooleanrequired
data.variant_name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
404

Not Found

errorstringrequired

Example: "Variant does not belong to this issue"

Example body, from the documented examples

{
  "error": "Variant does not belong to this issue"
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues/5432/variants/9001' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "id": 901,
    "issue_id": 5432,
    "variant_name": "Cover B",
    "cover_url": "https://...-cover_lg.webp",
    "images": {
      "thumb": "https://...-thumb.webp",
      "cover_sm": "https://...-cover_sm.webp",
      "cover_md": "https://...-cover_md.webp",
      "cover_lg": "https://...-cover_lg.webp"
    },
    "variant_type": "standard",
    "ratio": "1:25",
    "price": "4.99",
    "currency_code": "USD",
    "formatted_price": "$4.99",
    "ean": "75960609999300111",
    "release_date": "2025-04-09",
    "creators": [
      {
        "id": 101,
        "name": "J. Scott Campbell",
        "slug": "j-scott-campbell",
        "photo_url": "https://...-profile_md.webp",
        "role": "Cover Artist"
      }
    ],
    "variant_name_i18n": {
      "ja": {
        "value": "講談社",
        "reading": "こうだんしゃ",
        "source": "madb"
      }
    }
  }
}

Get key issue reasons.

GET/api/v1/issues/{issue_id}/key-reasons
Requires a token

Returns key issue reasons for a specific issue (e.g., "1st Appearance", "Death").

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataarray of objectsrequired
data[].idintegerrequired

Example: 1

data[].namestring or nullrequired

Example: "1st Appearance"

data[].categorystring or nullrequired

appearance, story, creator, market or media.

Example: "appearance"

data[].descriptionstring or nullrequired

Example: "First appearance of a character."

data[].notesstring or nullrequired

Example: "1st full appearance of Miles Morales"

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues/5432/key-reasons' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 1,
      "name": "1st Appearance",
      "category": "appearance",
      "description": "First appearance of a character.",
      "notes": "1st full appearance of Miles Morales"
    }
  ]
}

Get issue creators.

GET/api/v1/issues/{id}/creators
Requires a token

Returns paginated creators for a specific issue with their roles.

Path parameters

idintegerrequired

The issue ID.

Example: 5432

Query parameters

pageinteger

Page number; meta.last_page says where the list ends.

Example: 1

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes.

Example: "ja,ko"

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

current_pageintegerrequired

Example: 1

dataarray of objectsrequired
data[].idintegerrequired

Example: 789

data[].namestringrequired

Example: "Nick Spencer"

data[].slugstringrequired

Example: "nick-spencer"

data[].role_idinteger or nullrequired

Example: 1

data[].profile_photo_pathstring or nullrequired

Example: "uploads/creators/2024/01/nick-spencer.jpg"

data[].biographystring or nullrequired

Example: "An American comic book writer."

data[].genderstring or nullrequired

Example: "male"

data[].birthstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].deathstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].birth_placestring or nullrequired

Example: "Cincinnati, Ohio"

data[].countrystring or nullrequired

Example: "US"

data[].linksobject or nullrequired
data[].created_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].updated_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].deleted_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].aliasesarray of strings or nullrequired
data[].cached_issues_countintegerrequired

Example: 250

data[].cached_series_countintegerrequired

Example: 30

data[].cached_titles_countintegerrequired

Example: 20

data[].last_edited_byinteger or nullrequired

Example: 12

data[].last_edited_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].public_lists_countintegerrequired

Example: 4

data[].original_localestring or nullrequired

Example: "en"

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].aliases_i18nobjectrequired

Alternative names per language.

data[].roleobject or nullrequired
data[].role.idintegerrequired

Example: 1

data[].role.namestringrequired

Example: "Writer"

data[].role.descriptionstring or nullrequired

Example: "Writes the script."

data[].role.created_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].role.updated_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].pivotobjectrequired
data[].pivot.issue_idintegerrequired

Example: 5432

data[].pivot.creator_idintegerrequired

Example: 789

data[].pivot.creator_role_idinteger or nullrequired

Example: 1

data[].pivot.is_uncreditedbooleanrequired
data[].pivot.sort_orderinteger or nullrequired

Example: 0

data[].pivot.created_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].pivot.updated_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

first_page_urlstringrequired
frominteger or nullrequired

Example: 1

last_pageintegerrequired

Example: 1

last_page_urlstringrequired
linksarray of objectsrequired
links[].urlstring or nullrequired
links[].labelstringrequired
links[].pageinteger or null
links[].activebooleanrequired
next_page_urlstring or nullrequired
pathstringrequired
per_pageintegerrequired

Example: 50

prev_page_urlstring or nullrequired
tointeger or nullrequired

Example: 15

totalintegerrequired

Example: 15

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues/5432/creators' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "current_page": 1,
  "data": [
    {
      "id": 789,
      "name": "Nick Spencer",
      "slug": "nick-spencer",
      "role_id": 1,
      "profile_photo_path": "uploads/creators/2024/01/nick-spencer.jpg",
      "biography": "An American comic book writer.",
      "gender": "male",
      "birth": "2024-01-15T10:30:00.000000Z",
      "death": "2024-01-15T10:30:00.000000Z",
      "birth_place": "Cincinnati, Ohio",
      "country": "US",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "deleted_at": "2024-01-15T10:30:00.000000Z",
      "cached_issues_count": 250,
      "cached_series_count": 30,
      "cached_titles_count": 20,
      "last_edited_by": 12,
      "last_edited_at": "2024-01-15T10:30:00.000000Z",
      "public_lists_count": 4,
      "original_locale": "en",
      "name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      },
      "aliases_i18n": {
        "en": [
          "Kodansha Comics"
        ]
      },
      "role": {
        "id": 1,
        "name": "Writer",
        "description": "Writes the script.",
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      },
      "pivot": {
        "issue_id": 5432,
        "creator_id": 789,
        "creator_role_id": 1,
        "sort_order": 0,
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      }
    }
  ],
  "from": 1,
  "last_page": 1,
  "per_page": 50,
  "to": 15,
  "total": 15
}

Get issue characters.

GET/api/v1/issues/{id}/characters
Requires a token

Returns paginated characters appearing in a specific issue.

Path parameters

idintegerrequired

The issue ID.

Example: 5432

Query parameters

pageinteger

Page number; meta.last_page says where the list ends.

Example: 1

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes.

Example: "ja,ko"

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

current_pageintegerrequired

Example: 1

dataarray of objectsrequired
data[].idintegerrequired

Example: 456

data[].namestringrequired

Example: "Spider-Man"

data[].slugstringrequired

Example: "spider-man"

data[].real_namestring or nullrequired

Example: "Peter Parker"

data[].descriptionstring or nullrequired

Example: "Bitten by a radioactive spider."

data[].alter_egostring or number or boolean or array or object or nullrequired

Other identities, as stored: a list of strings in production.

Example: ["Spidey"]

data[].birthdaystring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].birth_placestring or nullrequired

Example: "Queens, New York"

data[].occupationstring or nullrequired

Example: "Photographer"

data[].heightstring or nullrequired

Example: "5'10\""

data[].weightstring or nullrequired

Example: "167 lbs"

data[].citizenshipstring or nullrequired

Example: "American"

data[].educationstring or nullrequired

Example: "College"

data[].aliasesarray of strings or nullrequired
data[].profile_photo_pathstring or nullrequired

Example: "uploads/characters/2024/01/spider-man.jpg"

data[].genderstring or nullrequired

Example: "male"

data[].created_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].updated_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].deleted_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].last_edited_byinteger or nullrequired

Example: 12

data[].last_edited_atstring or nullrequired

Example: "2024-01-15 10:30:00"

data[].public_lists_countintegerrequired

Example: 4

data[].debut_datestring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].debut_issue_idinteger or nullrequired

Example: 5432

data[].debut_editorialbooleanrequired
data[].original_localestring or nullrequired

Example: "en"

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].aliases_i18nobjectrequired

Alternative names per language.

data[].real_name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].racestring or nullrequired

Example: "Human"

data[].tagsarray of objectsrequired
data[].tags[].idintegerrequired

Example: 12

data[].tags[].nameobjectrequired
data[].tags[].slugobjectrequired
data[].tags[].typestring or nullrequired

Example: "ability"

data[].tags[].order_columninteger or nullrequired

Example: 1

data[].tags[].created_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].tags[].updated_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].tags[].pivotobjectrequired
data[].tags[].pivot.taggable_typestringrequired
data[].tags[].pivot.taggable_idintegerrequired

Example: 456

data[].tags[].pivot.tag_idintegerrequired

Example: 12

data[].pivotobjectrequired
data[].pivot.issue_idintegerrequired

Example: 5432

data[].pivot.character_idintegerrequired

Example: 456

data[].pivot.is_spoilerbooleanrequired
data[].pivot.sort_orderinteger or nullrequired

Example: 0

data[].pivot.created_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

data[].pivot.updated_atstring or nullrequired

Example: "2024-01-15T10:30:00.000000Z"

first_page_urlstringrequired
frominteger or nullrequired

Example: 1

last_pageintegerrequired

Example: 1

last_page_urlstringrequired
linksarray of objectsrequired
links[].urlstring or nullrequired
links[].labelstringrequired
links[].pageinteger or null
links[].activebooleanrequired
next_page_urlstring or nullrequired
pathstringrequired
per_pageintegerrequired

Example: 50

prev_page_urlstring or nullrequired
tointeger or nullrequired

Example: 15

totalintegerrequired

Example: 15

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}
429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

Example request

curl --request GET \
  'https://versedb.com/api/v1/issues/5432/characters' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "current_page": 1,
  "data": [
    {
      "id": 456,
      "name": "Spider-Man",
      "slug": "spider-man",
      "real_name": "Peter Parker",
      "description": "Bitten by a radioactive spider.",
      "alter_ego": [
        "Spidey"
      ],
      "birthday": "2024-01-15T10:30:00.000000Z",
      "birth_place": "Queens, New York",
      "occupation": "Photographer",
      "height": "5'10\"",
      "weight": "167 lbs",
      "citizenship": "American",
      "education": "College",
      "profile_photo_path": "uploads/characters/2024/01/spider-man.jpg",
      "gender": "male",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "deleted_at": "2024-01-15T10:30:00.000000Z",
      "last_edited_by": 12,
      "last_edited_at": "2024-01-15 10:30:00",
      "public_lists_count": 4,
      "debut_date": "2024-01-15T10:30:00.000000Z",
      "debut_issue_id": 5432,
      "original_locale": "en",
      "name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      },
      "aliases_i18n": {
        "en": [
          "Kodansha Comics"
        ]
      },
      "real_name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      },
      "race": "Human",
      "tags": [
        {
          "id": 12,
          "name": {
            "en": "Wall-crawling"
          },
          "slug": {
            "en": "wall-crawling"
          },
          "type": "ability",
          "order_column": 1,
          "created_at": "2024-01-15T10:30:00.000000Z",
          "updated_at": "2024-01-15T10:30:00.000000Z",
          "pivot": {
            "taggable_id": 456,
            "tag_id": 12
          }
        }
      ],
      "pivot": {
        "issue_id": 5432,
        "character_id": 456,
        "sort_order": 0,
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      }
    }
  ],
  "from": 1,
  "last_page": 1,
  "per_page": 50,
  "to": 15,
  "total": 15
}

Response headers

X-RateLimit-Limitinteger

Request quota per hour for your tier.

X-RateLimit-Remaininginteger

Requests remaining in the current window.

Retry-Afterinteger

Seconds to wait before retrying.