Skip to content
VerseDB

User

Endpoints for managing the authenticated user's pull list, follows, and reading progress.

All endpoints in this group require authentication with a Bearer API token.

Get the authenticated user.

GET/api/v1/user
Requires a token

Returns the profile of the user the token belongs to.

Needs read:user or read:showcase. A read:showcase token gets only id, name, username, bio, the avatar and banner fields, is_pro, the level and XP fields, created_at and updated_at: no email, location, birth date, preferences, or notification and account settings.

Responses

200

Success

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

dataobjectrequired
data.idintegerrequired

Example: 123

data.namestring or nullrequired

Example: "comic_fan_42"

data.usernamestring or nullrequired

Example: "comic_fan_42"

data.emailstring or null

Example: "[email protected]"

data.biostring or nullrequired

Example: "Comic collector since 1985"

data.avatarstring or nullrequired

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

data.profile_imagestring or nullrequired

Example: "users/123/comic-fan-42.jpg"

data.profile_image_urlstring or nullrequired

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

data.banner_pathstring or nullrequired

Example: null

data.banner_urlstring or nullrequired

Example: null

data.country_codestring or null

Example: "US"

data.citystring or null

Example: "New York"

data.regionstring or null

Example: "NY"

data.postal_codestring or null

Example: "10001"

data.formatted_locationstring or null

Example: "New York, NY, United States"

data.is_privateboolean or null

Example: false

data.is_wishlist_publicboolean or null

Example: true

data.public_wishlist_idstring or null

Example: "9d1c6b0e-7f0a-4c55-9a51-2f4a3f1d2b7e"

data.email_notificationsboolean or null

Example: true

data.content_edit_notificationsboolean or null

Example: true

data.comment_reply_notificationsboolean or null

Example: true

data.show_nsfw_warningsboolean or null

Example: true

data.birth_datestring or null

Example: "1990-05-01"

data.can_view_nsfwboolean

Example: true

data.show_reading_listboolean or null

Example: true

data.show_collectionboolean or null

Example: true

data.show_activityboolean or null

Example: true

data.show_followersboolean or null

Example: true

data.show_followingboolean or null

Example: true

data.show_spoilersboolean or null

Example: false

data.prompt_review_on_collectboolean

Example: false

data.preferred_mediumsarray of strings

Example: ["comic"]

data.preferred_genresarray

Example: []

data.preferred_languagesarray of strings

Example: ["en"]

data.localestring or null

Example: "en"

data.onboarding_completed_atstring or null

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

data.onboarding_stepinteger

Example: 0

data.ai_discovery_enabledboolean or null

Example: true

data.is_proboolean or nullrequired

Example: true

data.can_change_usernameboolean

Example: false

data.levelintegerrequired

Example: 5

data.xpintegerrequired

Example: 1200

data.xp_for_next_levelinteger or nullrequired

Example: 2000

data.xp_progress_percentnumberrequired

Example: 60

data.contributions_countintegerrequired

Example: 42

data.level_namestring or nullrequired

Example: "Collector"

data.created_atstring or nullrequired

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

data.updated_atstring or nullrequired

Example: "2026-06-20T14:32:00.000000Z"

data.has_passwordboolean

Example: true

data.deletion_requested_atstring or null

Example: null

data.deletion_confirmed_atstring or null

Example: null

data.deletion_scheduled_forstring or null

Example: null

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither read:user nor read:showcase.

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/user' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "id": 123,
    "name": "comic_fan_42",
    "username": "comic_fan_42",
    "email": "[email protected]",
    "bio": "Comic collector since 1985",
    "avatar": "https://...-profile_md.webp",
    "profile_image": "users/123/comic-fan-42.jpg",
    "profile_image_url": "https://...-profile_md.webp",
    "banner_path": null,
    "banner_url": null,
    "country_code": "US",
    "city": "New York",
    "region": "NY",
    "postal_code": "10001",
    "formatted_location": "New York, NY, United States",
    "is_private": false,
    "is_wishlist_public": true,
    "public_wishlist_id": "9d1c6b0e-7f0a-4c55-9a51-2f4a3f1d2b7e",
    "email_notifications": true,
    "content_edit_notifications": true,
    "comment_reply_notifications": true,
    "show_nsfw_warnings": true,
    "birth_date": "1990-05-01",
    "can_view_nsfw": true,
    "show_reading_list": true,
    "show_collection": true,
    "show_activity": true,
    "show_followers": true,
    "show_following": true,
    "show_spoilers": false,
    "prompt_review_on_collect": false,
    "preferred_mediums": [
      "comic"
    ],
    "preferred_genres": [],
    "preferred_languages": [
      "en"
    ],
    "locale": "en",
    "onboarding_completed_at": "2024-01-15T10:30:00.000000Z",
    "onboarding_step": 0,
    "ai_discovery_enabled": true,
    "is_pro": true,
    "can_change_username": false,
    "level": 5,
    "xp": 1200,
    "xp_for_next_level": 2000,
    "xp_progress_percent": 60,
    "contributions_count": 42,
    "level_name": "Collector",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2026-06-20T14:32:00.000000Z",
    "has_password": true,
    "deletion_requested_at": null,
    "deletion_confirmed_at": null,
    "deletion_scheduled_for": null
  }
}

List read status.

GET/api/v1/user/read-status
Requires a token

Returns all issues the user has marked as read with timestamps.

Needs read:user or read:showcase; both get the same response.

Query parameters

per_pageinteger

Items per page (max 100).

Example: 20

unreviewedboolean

When true, only returns reads for issues the user has not yet reviewed.

Example: true

qstring

Search your reads by series name or issue number.

Example: "saga 12"

sortstring

One of read_at_desc, read_at_asc, title_asc, title_desc. Default: newest marked first.

Example: "read_at_asc"

Responses

200

Success

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

dataarray of objectsrequired
data[].idintegerrequired

Example: 1234

data[].user_idintegerrequired

Example: 42

data[].readable_typestringrequired

Example: "Issue"

data[].readable_idintegerrequired

Example: 5432

data[].variant_idinteger or nullrequired

Example: null

data[].read_atstring or nullrequired

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

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[].readableobject or nullrequired

Null once the issue is gone.

data[].readable.idintegerrequired

Example: 5432

data[].readable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].readable.series_idinteger or nullrequired

Example: 123

data[].readable.issue_numberstring or nullrequired

Example: "1"

data[].readable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].readable.cover_datestring or nullrequired

Example: "2018-09-01"

data[].readable.release_datestring or nullrequired

Example: "2018-07-11"

data[].readable.foc_datestring or nullrequired

Example: "2018-06-18"

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

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

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

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

data[].readable.images.cover_smstring

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

data[].readable.images.cover_mdstring

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

data[].readable.images.cover_lgstring

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

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

Example: "Teen"

data[].readable.min_ageinteger or nullrequired

Example: 13

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

Example: 4.5

data[].readable.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

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

Example: 123

data[].readable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].readable.series.slugstring or nullrequired

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

data[].readable.series.start_yearinteger or nullrequired

Example: 2018

data[].readable.series.end_yearinteger or nullrequired

Example: 2022

data[].readable.series.volume_numberinteger or nullrequired

Example: 5

data[].readable.series.publication_typestring or nullrequired

Example: "regular_series"

data[].readable.series.formatstring or nullrequired

Example: "Standard"

data[].readable.series.cached_issues_countinteger or nullrequired

Example: 93

data[].readable.series.cover_urlstring or nullrequired

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

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

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

data[].readable.series.images.cover_mdstring

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

data[].readable.series.images.cover_lgstring

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

data[].readable.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 holds neither read:user nor read:showcase.

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/user/read-status' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 1234,
      "user_id": 42,
      "readable_type": "Issue",
      "readable_id": 5432,
      "variant_id": null,
      "read_at": "2024-01-15T10:30:00.000000Z",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "readable": {
        "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
  }
}

List wishlist.

GET/api/v1/user/wishlist
Requires a token

Returns the authenticated user's wishlist issues, most recently added first.

Needs read:user or read:showcase. A read:showcase token gets each item without note.

Query parameters

per_pageinteger

Items per page (max 100).

Example: 20

Responses

200

Success

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

dataarray of objectsrequired
data[].idintegerrequired

Example: 9876

data[].positioninteger or nullrequired

Example: null

data[].notestring or null

Left out for a read:showcase token.

Example: null

data[].created_atstringrequired

Example: "2024-01-15T10:30:00+00:00"

data[].updated_atstringrequired

Example: "2024-01-15T10:30:00+00:00"

data[].variant_idinteger or nullrequired

Example: null

data[].variantobject

The pinned cover, while it exists.

data[].variant.idintegerrequired

Example: 7

data[].variant.namestring or nullrequired

Example: "Cover B"

data[].variant.ratiostring or nullrequired

Example: "1:25"

data[].variant.cover_image_urlstring or nullrequired

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

data[].entity_typestringrequired

Example: "issues"

data[].entityobject

Left out once the issue is gone.

data[].entity.idintegerrequired

Example: 5432

data[].entity.slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].entity.namestring or nullrequired

Example: "Amazing Spider-Man #1"

data[].entity.issue_numberstring or nullrequired

Example: "1"

data[].entity.release_datestring or nullrequired

Example: "2018-07-11"

data[].entity.foc_datestring or nullrequired

Example: "2018-06-18"

data[].entity.image_urlstring or nullrequired

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

data[].entity.is_nsfwboolean or nullrequired
data[].entity.publisherstring or nullrequired

Example: "Marvel"

data[].entity.seriesobject or nullrequired
data[].entity.series.idintegerrequired

Example: 123

data[].entity.series.namestring or nullrequired

Example: "Amazing Spider-Man"

data[].entity.series.slugstring or nullrequired

Example: "amazing-spider-man-2018"

data[].entity.series.start_yearinteger or nullrequired

Example: 2018

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 holds neither read:user nor read:showcase.

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/user/wishlist' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 9876,
      "position": null,
      "note": null,
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00",
      "variant_id": null,
      "variant": {
        "id": 7,
        "name": "Cover B",
        "ratio": "1:25",
        "cover_image_url": "https://...-cover_md.webp"
      },
      "entity_type": "issues",
      "entity": {
        "id": 5432,
        "slug": "amazing-spider-man-1",
        "name": "Amazing Spider-Man #1",
        "issue_number": "1",
        "release_date": "2018-07-11",
        "foc_date": "2018-06-18",
        "image_url": "https://...-cover_md.webp",
        "publisher": "Marvel",
        "series": {
          "id": 123,
          "name": "Amazing Spider-Man",
          "slug": "amazing-spider-man-2018",
          "start_year": 2018
        }
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

List collection.

GET/api/v1/user/collections
Requires a token

Returns the issues in the user's collection, newest added first, each with its issue, series and publisher.

Needs read:user or read:showcase. A read:showcase token gets each copy without price_paid, estimated_value, value_last_updated, price_sold, sold_at, purchased_at, purchase_source, purchase_store, acquisition_method, comic_shop_id, comic_shop, notes, grader_notes, storage_location, custom_label, bagged_at, personal_rating, tags or loan, leaves out copies marked not public, and the estimated_value and price_paid sorts fall back to date_added.

Query parameters

per_pageinteger

Items per page (max 100).

Example: 20

pageinteger

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

Example: 1

searchstring

Filter by issue name, issue number, or series name.

Example: "spider"

formatstring

Filter by stored format.

Example: "single"

gradedboolean

Filter to graded (true) or raw (false) copies.

Example: true

is_signedboolean

Filter to signed (true) or unsigned (false) copies. PRO; ignored for other members.

Example: true

conditionstring

Filter by condition grade code.

Example: "NM"

statusstring

Which copies to return: owned, for_sale, sold, or all. Sold copies are excluded by default.

Example: "sold"

for_saleboolean

Filter to copies marked for sale.

Example: true

for_tradeboolean

Filter to copies marked for trade.

Example: true

read_statusstring

Filter by read state. One of: read, unread.

Example: "unread"

publisher_idinteger

Filter to issues from a publisher.

Example: 1

series_idinteger

Filter to copies of issues in a series.

Example: 123

grade_minnumber

Filter to copies with a numeric grade at or above this value. PRO; ignored for other members.

Example: 9

grade_maxnumber

Filter to copies with a numeric grade at or below this value. PRO; ignored for other members.

Example: 9.8

sort_bystring

Sort field. One of: date_added, title, release_date, estimated_value, price_paid.

Example: "title"

sort_orderstring

Sort direction. One of: asc, desc.

Example: "asc"

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: 1001

data[].user_idintegerrequired

Example: 42

data[].collectable_typestringrequired

Example: "Issue"

data[].collectable_idintegerrequired

Example: 5432

data[].variant_idinteger or nullrequired

Example: null

data[].conditionstring or nullrequired

Example: "NM"

data[].purchased_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data[].notesstring or null

Left out for a read:showcase token.

Example: "First print"

data[].formatstring or nullrequired

Example: "single"

data[].storage_locationstring or null

Left out for a read:showcase token.

Example: "Long box 3"

data[].price_paidstring or null

Left out for a read:showcase token.

Example: "3.99"

data[].is_variantboolean or nullrequired
data[].variant_descriptionstring or nullrequired

Example: "Cover B"

data[].variant_typestring or nullrequired

Example: "cover"

data[].gradedboolean or nullrequired
data[].grade_scorestring or nullrequired

Example: "9.8"

data[].grading_companystring or nullrequired

Example: "CGC"

data[].grading_numberstring or nullrequired

Example: "1234567001"

data[].label_typestring or nullrequired

Example: "universal"

data[].page_qualitystring or nullrequired

Example: "white"

data[].grader_notesstring or null

Left out for a read:showcase token.

Example: "Light spine stress"

data[].purchase_sourcestring or null

Left out for a read:showcase token.

Example: "lcs"

data[].comic_shop_idinteger or null

Left out for a read:showcase token.

Example: 17

data[].comic_shopobject

The shop the copy came from, while it is listed; left out otherwise and for a read:showcase token.

data[].comic_shop.idintegerrequired

Example: 17

data[].comic_shop.namestring or nullrequired

Example: "Comic Corner"

data[].comic_shop.slugstring or nullrequired

Example: "comic-corner"

data[].comic_shop.citystring or nullrequired

Example: "Portland"

data[].comic_shop.state_provincestring or nullrequired

Example: "OR"

data[].acquisition_methodstring or null

Left out for a read:showcase token.

Example: "purchased"

data[].purchase_storestring or null

Left out for a read:showcase token.

Example: "Comic Corner"

data[].custom_labelstring or null

Left out for a read:showcase token.

Example: "Keys"

data[].bagged_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data[].personal_ratingstring or null

Left out for a read:showcase token.

Example: "4.5"

data[].tagsarray of strings

Left out for a read:showcase token.

Example: ["keys"]

data[].loanobject or null

Left out for a read:showcase token.

data[].loan.idintegerrequired

Example: 3

data[].loan.loaned_tostring or nullrequired

Example: "Sam"

data[].loan.loaned_atstring or nullrequired

Example: "2024-01-15"

data[].loan.due_atstring or nullrequired

Example: "2024-02-15"

data[].loan.is_overduebooleanrequired
data[].loan.days_until_dueinteger or nullrequired

Example: 12

data[].is_signedboolean or nullrequired
data[].signed_bystring or nullrequired

Example: "Stan Lee"

data[].signature_witnessstring or nullrequired

Example: "CGC"

data[].signature_authenticatedbooleanrequired
data[].is_cgc_ssbooleanrequired
data[].print_numberstring or nullrequired

Example: "1"

data[].estimated_valuestring or null

Left out for a read:showcase token.

Example: "125.00"

data[].value_last_updatedstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data[].statusstring or nullrequired

owned, for_sale or sold.

Example: "owned"

data[].for_saleboolean or nullrequired
data[].for_tradeboolean or nullrequired
data[].sold_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data[].price_soldstring or null

Left out for a read:showcase token.

Example: "150.00"

data[].is_publicboolean or nullrequired
data[].cover_scan_urlstring or nullrequired

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

data[].cover_scan_url_lgstring or nullrequired

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

data[].cover_scan_uploaded_atstring or nullrequired

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

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[].collectableobject or nullrequired

Null once the issue is gone.

data[].collectable.idintegerrequired

Example: 5432

data[].collectable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].collectable.series_idinteger or nullrequired

Example: 123

data[].collectable.issue_numberstring or nullrequired

Example: "1"

data[].collectable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].collectable.cover_datestring or nullrequired

Example: "2018-09-01"

data[].collectable.release_datestring or nullrequired

Example: "2018-07-11"

data[].collectable.foc_datestring or nullrequired

Example: "2018-06-18"

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

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

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

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

data[].collectable.images.cover_smstring

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

data[].collectable.images.cover_mdstring

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

data[].collectable.images.cover_lgstring

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

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

Example: "Teen"

data[].collectable.min_ageinteger or nullrequired

Example: 13

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

Example: 4.5

data[].collectable.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

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

Example: 123

data[].collectable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].collectable.series.slugstring or nullrequired

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

data[].collectable.series.start_yearinteger or nullrequired

Example: 2018

data[].collectable.series.end_yearinteger or nullrequired

Example: 2022

data[].collectable.series.volume_numberinteger or nullrequired

Example: 5

data[].collectable.series.publication_typestring or nullrequired

Example: "regular_series"

data[].collectable.series.formatstring or nullrequired

Example: "Standard"

data[].collectable.series.cached_issues_countinteger or nullrequired

Example: 93

data[].collectable.series.cover_urlstring or nullrequired

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

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

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

data[].collectable.series.images.cover_mdstring

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

data[].collectable.series.images.cover_lgstring

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

data[].collectable.series.publisher_namestring or nullrequired

Example: "Marvel"

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

Example: 7

data[].collectable.key_issue_reasons[].namestring or nullrequired

Example: "First appearance"

data[].collectable.key_issue_reasons[].categorystringrequired

Example: "appearance"

data[].collectable.key_issue_reasons[].slugstring or nullrequired

Example: "first-appearance"

data[].collectable.key_issue_reasons[].notesstring or nullrequired

Example: "Cameo"

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 holds neither read:user nor read:showcase.

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/user/collections' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 1001,
      "user_id": 42,
      "collectable_type": "Issue",
      "collectable_id": 5432,
      "variant_id": null,
      "condition": "NM",
      "purchased_at": "2024-01-15T00:00:00.000000Z",
      "notes": "First print",
      "format": "single",
      "storage_location": "Long box 3",
      "price_paid": "3.99",
      "variant_description": "Cover B",
      "variant_type": "cover",
      "grade_score": "9.8",
      "grading_company": "CGC",
      "grading_number": "1234567001",
      "label_type": "universal",
      "page_quality": "white",
      "grader_notes": "Light spine stress",
      "purchase_source": "lcs",
      "comic_shop_id": 17,
      "comic_shop": {
        "id": 17,
        "name": "Comic Corner",
        "slug": "comic-corner",
        "city": "Portland",
        "state_province": "OR"
      },
      "acquisition_method": "purchased",
      "purchase_store": "Comic Corner",
      "custom_label": "Keys",
      "bagged_at": "2024-01-15T00:00:00.000000Z",
      "personal_rating": "4.5",
      "tags": [
        "keys"
      ],
      "loan": {
        "id": 3,
        "loaned_to": "Sam",
        "loaned_at": "2024-01-15",
        "due_at": "2024-02-15",
        "days_until_due": 12
      },
      "signed_by": "Stan Lee",
      "signature_witness": "CGC",
      "print_number": "1",
      "estimated_value": "125.00",
      "value_last_updated": "2024-01-15T00:00:00.000000Z",
      "status": "owned",
      "sold_at": "2024-01-15T00:00:00.000000Z",
      "price_sold": "150.00",
      "cover_scan_url": "https://...-cover_md.webp",
      "cover_scan_url_lg": "https://...-cover_lg.webp",
      "cover_scan_uploaded_at": "2024-01-15T10:30:00.000000Z",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "collectable": {
        "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"
        },
        "key_issue_reasons": [
          {
            "id": 7,
            "name": "First appearance",
            "category": "appearance",
            "slug": "first-appearance",
            "notes": "Cameo"
          }
        ]
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

Check issue in collection.

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

Checks if an issue (optionally a specific variant) is in the user's collection: the copies still held (sold ones left out), oldest first, and the first of them in full.

Needs read:user.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Query parameters

variant_idinteger

Specific variant ID to check (optional).

Example: 789

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

in_collectionbooleanrequired
is_unreleasedbooleanrequired

The issue is more than a day from its release, so it cannot be added yet.

copies_countintegerrequired

Example: 1

copiesarray of objectsrequired
copies[].idintegerrequired

Example: 1001

copies[].variant_idinteger or nullrequired

Example: 789

copies[].conditionstring or nullrequired

Example: "NM"

copies[].gradedbooleanrequired
copies[].grade_scorestring or nullrequired

Example: "9.8"

copies[].grading_companystring or nullrequired

Example: "CGC"

copies[].is_signedbooleanrequired
copies[].signed_bystring or nullrequired

Example: "Stan Lee"

copies[].is_cgc_ssbooleanrequired
copies[].formatstring or nullrequired

Example: "single"

copies[].storage_locationstring or nullrequired

Example: "Long box 3"

copies[].purchased_atstring or nullrequired

Example: "2024-01-15T00:00:00+00:00"

copies[].notesstring or nullrequired

Example: "First print"

copies[].created_atstring or nullrequired

Example: "2024-01-15T10:30:00+00:00"

copies[].updated_atstring or nullrequired

Example: "2024-01-15T10:30:00+00:00"

dataobject or nullrequired

The first copy, or null when there is none.

data.idintegerrequired

Example: 1001

data.user_idintegerrequired

Example: 42

data.collectable_typestringrequired

Example: "Issue"

data.collectable_idintegerrequired

Example: 5432

data.variant_idinteger or nullrequired

Example: null

data.conditionstring or nullrequired

Example: "NM"

data.purchased_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.notesstring or null

Left out for a read:showcase token.

Example: "First print"

data.formatstring or nullrequired

Example: "single"

data.storage_locationstring or null

Left out for a read:showcase token.

Example: "Long box 3"

data.price_paidstring or null

Left out for a read:showcase token.

Example: "3.99"

data.is_variantboolean or nullrequired
data.variant_descriptionstring or nullrequired

Example: "Cover B"

data.variant_typestring or nullrequired

Example: "cover"

data.gradedboolean or nullrequired
data.grade_scorestring or nullrequired

Example: "9.8"

data.grading_companystring or nullrequired

Example: "CGC"

data.grading_numberstring or nullrequired

Example: "1234567001"

data.label_typestring or nullrequired

Example: "universal"

data.page_qualitystring or nullrequired

Example: "white"

data.grader_notesstring or null

Left out for a read:showcase token.

Example: "Light spine stress"

data.purchase_sourcestring or null

Left out for a read:showcase token.

Example: "lcs"

data.comic_shop_idinteger or null

Left out for a read:showcase token.

Example: 17

data.acquisition_methodstring or null

Left out for a read:showcase token.

Example: "purchased"

data.purchase_storestring or null

Left out for a read:showcase token.

Example: "Comic Corner"

data.custom_labelstring or null

Left out for a read:showcase token.

Example: "Keys"

data.bagged_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.personal_ratingstring or null

Left out for a read:showcase token.

Example: "4.5"

data.tagsarray of strings

Left out for a read:showcase token.

Example: ["keys"]

data.loanobject or null

Left out for a read:showcase token.

data.loan.idintegerrequired

Example: 3

data.loan.loaned_tostring or nullrequired

Example: "Sam"

data.loan.loaned_atstring or nullrequired

Example: "2024-01-15"

data.loan.due_atstring or nullrequired

Example: "2024-02-15"

data.loan.is_overduebooleanrequired
data.loan.days_until_dueinteger or nullrequired

Example: 12

data.is_signedboolean or nullrequired
data.signed_bystring or nullrequired

Example: "Stan Lee"

data.signature_witnessstring or nullrequired

Example: "CGC"

data.signature_authenticatedbooleanrequired
data.is_cgc_ssbooleanrequired
data.print_numberstring or nullrequired

Example: "1"

data.estimated_valuestring or null

Left out for a read:showcase token.

Example: "125.00"

data.value_last_updatedstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.statusstring or nullrequired

owned, for_sale or sold.

Example: "owned"

data.for_saleboolean or nullrequired
data.for_tradeboolean or nullrequired
data.sold_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.price_soldstring or null

Left out for a read:showcase token.

Example: "150.00"

data.is_publicboolean or nullrequired
data.cover_scan_urlstring or nullrequired

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

data.cover_scan_url_lgstring or nullrequired

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

data.cover_scan_uploaded_atstring or nullrequired

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

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.collectableobject or nullrequired

The issue with its series.

data.collectable.idintegerrequired

Example: 5432

data.collectable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data.collectable.series_idinteger or nullrequired

Example: 123

data.collectable.issue_numberstring or nullrequired

Example: "1"

data.collectable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data.collectable.cover_datestring or nullrequired

Example: "2018-09-01"

data.collectable.release_datestring or nullrequired

Example: "2018-07-11"

data.collectable.foc_datestring or nullrequired

Example: "2018-06-18"

data.collectable.is_unreleasedbooleanrequired
data.collectable.cover_urlstring or nullrequired

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

data.collectable.imagesobject or nullrequired
data.collectable.images.thumbstring

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

data.collectable.images.cover_smstring

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

data.collectable.images.cover_mdstring

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

data.collectable.images.cover_lgstring

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

data.collectable.is_reprintbooleanrequired
data.collectable.content_rating_labelstring or nullrequired

Example: "Teen"

data.collectable.min_ageinteger or nullrequired

Example: 13

data.collectable.is_nsfwbooleanrequired
data.collectable.average_ratingnumber or nullrequired

Example: 4.5

data.collectable.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data.collectable.seriesobject or null
data.collectable.series.idintegerrequired

Example: 123

data.collectable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.collectable.series.slugstring or nullrequired

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

data.collectable.series.start_yearinteger or nullrequired

Example: 2018

data.collectable.series.end_yearinteger or nullrequired

Example: 2022

data.collectable.series.volume_numberinteger or nullrequired

Example: 5

data.collectable.series.publication_typestring or nullrequired

Example: "regular_series"

data.collectable.series.formatstring or nullrequired

Example: "Standard"

data.collectable.series.cached_issues_countinteger or nullrequired

Example: 93

data.collectable.series.cover_urlstring or nullrequired

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

data.collectable.series.imagesobject or nullrequired
data.collectable.series.images.cover_smstring

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

data.collectable.series.images.cover_mdstring

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

data.collectable.series.images.cover_lgstring

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

data.collectable.series.publisher_namestring or nullrequired

Example: "Marvel"

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token does not hold read:user.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

A variant that does not exist.

messagestringrequired

Example: "The selected variant id is invalid."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The selected variant id is invalid.",
  "errors": {
    "variant_id": [
      "The selected variant id is invalid."
    ]
  }
}
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/collection/check' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "copies_count": 1,
  "copies": [
    {
      "id": 1001,
      "variant_id": 789,
      "condition": "NM",
      "grade_score": "9.8",
      "grading_company": "CGC",
      "signed_by": "Stan Lee",
      "format": "single",
      "storage_location": "Long box 3",
      "purchased_at": "2024-01-15T00:00:00+00:00",
      "notes": "First print",
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00"
    }
  ],
  "data": {
    "id": 1001,
    "user_id": 42,
    "collectable_type": "Issue",
    "collectable_id": 5432,
    "variant_id": null,
    "condition": "NM",
    "purchased_at": "2024-01-15T00:00:00.000000Z",
    "notes": "First print",
    "format": "single",
    "storage_location": "Long box 3",
    "price_paid": "3.99",
    "variant_description": "Cover B",
    "variant_type": "cover",
    "grade_score": "9.8",
    "grading_company": "CGC",
    "grading_number": "1234567001",
    "label_type": "universal",
    "page_quality": "white",
    "grader_notes": "Light spine stress",
    "purchase_source": "lcs",
    "comic_shop_id": 17,
    "acquisition_method": "purchased",
    "purchase_store": "Comic Corner",
    "custom_label": "Keys",
    "bagged_at": "2024-01-15T00:00:00.000000Z",
    "personal_rating": "4.5",
    "tags": [
      "keys"
    ],
    "loan": {
      "id": 3,
      "loaned_to": "Sam",
      "loaned_at": "2024-01-15",
      "due_at": "2024-02-15",
      "days_until_due": 12
    },
    "signed_by": "Stan Lee",
    "signature_witness": "CGC",
    "print_number": "1",
    "estimated_value": "125.00",
    "value_last_updated": "2024-01-15T00:00:00.000000Z",
    "status": "owned",
    "sold_at": "2024-01-15T00:00:00.000000Z",
    "price_sold": "150.00",
    "cover_scan_url": "https://...-cover_md.webp",
    "cover_scan_url_lg": "https://...-cover_lg.webp",
    "cover_scan_uploaded_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "collectable": {
      "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"
      }
    }
  }
}

List pull list.

GET/api/v1/user/pull-list
Requires a token

Returns all series on the user's pull list (series they're tracking for new releases), most recently added first.

Needs read:user or read:showcase. A read:showcase token gets each entry without personal_notes, notify_on_release, notification_settings, auto_pull, last_pulled_at, preferred_cover_type, pull_priority or the pull source fields.

Query parameters

per_pageinteger

Items per page (max 100).

Example: 20

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

dataarray of objectsrequired
data[].idintegerrequired

Example: 1234

data[].user_idintegerrequired

Example: 42

data[].pullable_typestring or nullrequired

Example: "Series"

data[].pullable_idinteger or nullrequired

Example: 456

data[].series_idinteger or nullrequired

Example: 456

data[].variant_idinteger or nullrequired

Example: null

data[].statusstringrequired

active, paused or canceled.

Example: "active"

data[].auto_pullboolean or null

Left out for a read:showcase token.

data[].last_pulled_atstring or null

Left out for a read:showcase token.

data[].preferred_cover_typestring or null

Left out for a read:showcase token.

data[].pull_priorityinteger or null

Left out for a read:showcase token.

data[].notify_on_releaseboolean or null

Left out for a read:showcase token.

data[].notification_settingsstring or number or boolean or array or object or null

Left out for a read:showcase token.

data[].personal_notesstring or null

Left out for a read:showcase token.

data[].pull_source_idsarray of integers

Left out for a read:showcase token.

data[].pull_sourcesarray of objects

Left out for a read:showcase token.

data[].pull_sources[].idintegerrequired

Example: 12

data[].pull_sources[].namestringrequired

Example: "Main Street Comics"

data[].pull_sources[].kindstringrequired

Example: "shop"

data[].pull_sources[].kind_labelstringrequired

Example: "Comic shop"

data[].pull_sources[].has_pickupbooleanrequired
data[].pull_sources[].comic_shop_idinteger or nullrequired

Example: 345

data[].pull_sources[].locationstring or nullrequired

Example: "Springfield, IL"

data[].pull_sources[].pickup_notestring or nullrequired

Example: "Ships Friday"

data[].pull_sources[].is_defaultbooleanrequired
data[].pull_sources[].is_linkedbooleanrequired

True when the source is a shop's own link to the member's account.

data[].pull_sources[].shop_link_idinteger or nullrequired

Example: null

data[].pull_sources[].sortintegerrequired

Example: 1

data[].pull_sources[].created_atstring or nullrequired

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

data[].pull_sources[].updated_atstring or nullrequired

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

data[].pull_source_idinteger or null

Left out for a read:showcase token.

data[].pull_sourceobject or null

Left out for a read:showcase token.

data[].pull_source.idintegerrequired

Example: 12

data[].pull_source.namestringrequired

Example: "Main Street Comics"

data[].pull_source.kindstringrequired

Example: "shop"

data[].pull_source.kind_labelstringrequired

Example: "Comic shop"

data[].pull_source.has_pickupbooleanrequired
data[].pull_source.comic_shop_idinteger or nullrequired

Example: 345

data[].pull_source.locationstring or nullrequired

Example: "Springfield, IL"

data[].pull_source.pickup_notestring or nullrequired

Example: "Ships Friday"

data[].pull_source.is_defaultbooleanrequired
data[].pull_source.is_linkedbooleanrequired

True when the source is a shop's own link to the member's account.

data[].pull_source.shop_link_idinteger or nullrequired

Example: null

data[].pull_source.sortintegerrequired

Example: 1

data[].pull_source.created_atstring or nullrequired

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

data[].pull_source.updated_atstring or nullrequired

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

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[].series_namestring or nullrequired

Null once the series is gone.

Example: "The Amazing Spider-Man"

data[].series_cover_urlstring or nullrequired

Example: "https://...-cover_md.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[].publisher_namestring or nullrequired

Example: "Marvel"

data[].is_nsfwbooleanrequired
data[].next_issueobject or nullrequired

The series' next issue released today or later that the member hasn't skipped.

data[].next_issue.idintegerrequired

Example: 5432

data[].next_issue.slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].next_issue.series_idinteger or nullrequired

Example: 123

data[].next_issue.issue_numberstring or nullrequired

Example: "1"

data[].next_issue.namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].next_issue.cover_datestring or nullrequired

Example: "2018-09-01"

data[].next_issue.release_datestring or nullrequired

Example: "2018-07-11"

data[].next_issue.foc_datestring or nullrequired

Example: "2018-06-18"

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

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

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

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

data[].next_issue.images.cover_smstring

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

data[].next_issue.images.cover_mdstring

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

data[].next_issue.images.cover_lgstring

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

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

Example: "Teen"

data[].next_issue.min_ageinteger or nullrequired

Example: 13

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

Example: 4.5

data[].next_issue.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].seriesobject or nullrequired

Null once the series is gone.

data[].series.idintegerrequired

Example: 123

data[].series.title_idinteger or nullrequired

Example: 1

data[].series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].series.display_namestringrequired

Example: "The Amazing Spider-Man (2018)"

data[].series.slugstring or nullrequired

Example: "amazing-spider-man-2018"

data[].series.numberinteger or nullrequired

Example: 6

data[].series.start_yearinteger or nullrequired

Example: 2018

data[].series.end_yearinteger or nullrequired

Example: 2022

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.mediumstring or nullrequired

Example: "comic"

data[].series.publication_typestring or nullrequired

Example: "regular_series"

data[].series.formatstring or nullrequired

Example: "Standard"

data[].series.statusstring or nullrequired

Example: "Ongoing"

data[].series.original_namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].series.original_languagestring or nullrequired

Example: "en"

data[].series.languagestring or nullrequired

Example: "en"

data[].series.cached_issues_countinteger or nullrequired

Example: 94

data[].series.average_ratingstring or nullrequired

Example: "4.25"

data[].series.total_reviewsinteger or nullrequired

Example: 12

data[].series.issues_average_ratingstring or nullrequired

Example: "4.10"

data[].series.issues_rated_countinteger or nullrequired

Example: 40

data[].series.content_rating_labelstring or nullrequired

Example: "Teen"

data[].series.min_ageinteger or nullrequired

Example: 13

data[].series.is_nsfwboolean or nullrequired
data[].series.publisher_namestring or nullrequired

Example: "Marvel"

data[].series.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].series.aliases_i18nobjectrequired

Alternative names per language.

data[].series.original_localestring or nullrequired

The language the series is from, a BCP 47 tag.

Example: "ja"

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 holds neither read:user nor read:showcase.

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/user/pull-list' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 1234,
      "user_id": 42,
      "pullable_type": "Series",
      "pullable_id": 456,
      "series_id": 456,
      "variant_id": null,
      "status": "active",
      "pull_sources": [
        {
          "id": 12,
          "name": "Main Street Comics",
          "kind": "shop",
          "kind_label": "Comic shop",
          "comic_shop_id": 345,
          "location": "Springfield, IL",
          "pickup_note": "Ships Friday",
          "shop_link_id": null,
          "sort": 1,
          "created_at": "2024-01-15T10:30:00.000000Z",
          "updated_at": "2024-01-15T10:30:00.000000Z"
        }
      ],
      "pull_source": {
        "id": 12,
        "name": "Main Street Comics",
        "kind": "shop",
        "kind_label": "Comic shop",
        "comic_shop_id": 345,
        "location": "Springfield, IL",
        "pickup_note": "Ships Friday",
        "shop_link_id": null,
        "sort": 1,
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      },
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "series_name": "The Amazing Spider-Man",
      "series_cover_url": "https://...-cover_md.webp",
      "series_images": {
        "cover_sm": "https://...-cover_sm.webp",
        "cover_md": "https://...-cover_md.webp",
        "cover_lg": "https://...-cover_lg.webp"
      },
      "publisher_name": "Marvel",
      "next_issue": {
        "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,
        "title_id": 1,
        "name": "The Amazing Spider-Man",
        "display_name": "The Amazing Spider-Man (2018)",
        "slug": "amazing-spider-man-2018",
        "number": 6,
        "start_year": 2018,
        "end_year": 2022,
        "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"
        },
        "medium": "comic",
        "publication_type": "regular_series",
        "format": "Standard",
        "status": "Ongoing",
        "original_name": "The Amazing Spider-Man",
        "original_language": "en",
        "language": "en",
        "cached_issues_count": 94,
        "average_rating": "4.25",
        "total_reviews": 12,
        "issues_average_rating": "4.10",
        "issues_rated_count": 40,
        "content_rating_label": "Teen",
        "min_age": 13,
        "publisher_name": "Marvel",
        "name_i18n": {
          "ja": {
            "value": "講談社",
            "reading": "こうだんしゃ",
            "source": "madb"
          }
        },
        "aliases_i18n": {
          "en": [
            "Kodansha Comics"
          ]
        },
        "original_locale": "ja"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

Mark as read.

POST/api/v1/issues/{issue_id}/read-status
Requires a token

Marks an issue (optionally a specific variant) as read with the current timestamp.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Request body application/json

variant_idinteger or null

Specific variant ID (optional).

Example: 789

Responses

201

Success. series_completed is there when this read finishes the series.

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

series_completedobject

Every live issue of the series is now read.

series_completed.series_idintegerrequired

Example: 123

series_completed.series_namestring or nullrequired

Example: "Saga"

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:read-status nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID.

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"
}
422

Invalid Variant, a variant that does not exist, or an issue not released yet.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 POST \
  'https://versedb.com/api/v1/issues/5432/read-status' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "variant_id": 789
}'

Example response 201

{
  "series_completed": {
    "series_id": 123,
    "series_name": "Saga"
  }
}

Edit reading date.

PATCH/api/v1/issues/{issue_id}/read-status
Requires a token

Updates the read_at date on an existing read entry, or removes the entry when read_at is null. If no entry exists yet and a date is provided, one is created (upsert).

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Request body application/json

read_atstring or null

Date in YYYY-MM-DD format, must not be in the future. Pass null to mark as unread.

Example: "2026-03-01"

variant_idinteger or null

Specific variant ID (optional).

Example: 789

Responses

200

Updated

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

read_atstringrequired

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

204

Cleared (read_at was null)

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

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:read-status nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID.

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"
}
422

Invalid Variant, a date after today, or an issue not released yet.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 PATCH \
  'https://versedb.com/api/v1/issues/5432/read-status' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "read_at": "2026-03-01",
  "variant_id": 789
}'

Example response 200

{
  "read_at": "2026-03-01T00:00:00+00:00"
}

Mark as unread.

DELETE/api/v1/issues/{issue_id}/read-status
Requires a token

Removes the read status for an issue (optionally a specific variant).

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Request body application/json

variant_idinteger or null

Specific variant ID (optional).

Example: 789

Responses

204

Removed

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

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:read-status nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID.

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"
}
422

A variant that does not exist.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 DELETE \
  'https://versedb.com/api/v1/issues/5432/read-status' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "variant_id": 789
}'

Add to wishlist.

POST/api/v1/issues/{issue_id}/wishlist
Requires a token

Adds the issue to the authenticated user's wishlist. Idempotent: calling with an issue already on the wishlist returns 200 without creating a duplicate.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Request body application/json

variant_idinteger or null

Optional cover variant to pin. Must belong to the issue. Omit for "any cover". The same issue may sit on the wishlist once per distinct variant plus once variant-less.

Example: 789

Responses

200

Already in Wishlist

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

in_wishlistbooleanrequired

Example: true

variant_idinteger or nullrequired

Example: 7

201

Added

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

in_wishlistbooleanrequired

Example: true

variant_idinteger or nullrequired

Example: 7

Example body, from the documented examples

{
  "in_wishlist": true,
  "variant_id": 7
}
401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:wishlist nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID.

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"
}
422

Wishlist Full, or a variant that is not one of the issue's.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 POST \
  'https://versedb.com/api/v1/issues/5432/wishlist' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "variant_id": 789
}'

Example response 200

{
  "in_wishlist": true,
  "variant_id": 7
}

Remove from wishlist.

DELETE/api/v1/issues/{issue_id}/wishlist
Requires a token

Removes the issue from the authenticated user's wishlist. Idempotent: returns 204 whether or not the issue was on the wishlist.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Query parameters

variant_idinteger

Optional cover variant to remove. Omit to remove the "any cover" entry — variant-pinned entries for the same issue are left alone.

Example: 7

Responses

204

Removed

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

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:wishlist nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID.

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"
}
422

A variant that is not one of the issue's.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 DELETE \
  'https://versedb.com/api/v1/issues/5432/wishlist' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Add to pull list.

POST/api/v1/pull-list/items
Requires a token

Adds a series to the user's pull list to track new releases. Adding a series already on it changes nothing.

Request body application/json

series_idintegerrequired

The series ID to add.

Example: 456

Responses

201

Added

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

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:pull-list nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

The series is deleted.

messagestringrequired

Example: "No query results for model [App\\Models\\Series] 456"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\Series] 456"
}
422

No series has this ID.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 POST \
  'https://versedb.com/api/v1/pull-list/items' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "series_id": 456
}'

Example response 201

[]

Remove from pull list.

DELETE/api/v1/pull-list/items/{item_id}
Requires a token

Removes a series from the authenticated user's pull list. Idempotent: returns 204 whether or not the series was on it.

Path parameters

item_idintegerrequired

The series ID of the pull list entry.

Example: 456

Responses

204

Removed

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

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:pull-list nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live series has this ID.

messagestringrequired

Example: "No query results for model [App\\Models\\Series] 456"

Example body, from the documented examples

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

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 DELETE \
  'https://versedb.com/api/v1/pull-list/items/456' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Add issue to collection.

POST/api/v1/issues/{issue_id}/collection
Requires a token

Adds a copy of the issue to the user's collection; every field is optional. When the issue was on the user's wishlist it comes off when the user chose that, else was_on_wishlist is true so the app can offer it. follow_up says whether to offer marking it read or reviewing it.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Request body application/json

variant_idinteger or null

Link to a specific issue variant. Must belong to the issue. Must match an existing stored value.

Example: 42

conditionstring or null

Comic condition grade (CGC scale). One of: MT, NM/MT, NM+, NM, NM-, VF/NM, VF+, VF, VF-, F/VF, F+, F, F-, VG/F, VG+, VG, VG-, G/VG, G, FR, PR.

Example: "NM"

notesstring or null

User notes about this copy. Must not be greater than 1000 characters.

Example: "First print, great condition"

price_paidnumber or null

Purchase price in dollars. Must be at least 0. Must not be greater than 999999.99.

Example: 3.99

formatstring or null

Physical format of the copy. One of: standard, trade_paperback, hardcover, omnibus, deluxe_edition, annual, graphic_novel, digital, treasury, magazine, prestige, digest, other.

Example: "standard"

purchase_sourcestring or null

Where the comic was purchased. One of: comic_shop, online_retailer, auction, convention, private_seller, subscription, digital_platform, second_hand_store, inheritance, gift, trade, other.

Example: "comic_shop"

purchase_storestring or null

Name of the store the copy was bought from, as free text. Use comic_shop_id instead where the shop is one VerseDB catalogs. Must not be greater than 255 characters.

Example: "Third Eye Comics"

custom_labelstring or null

The collector's own label for this copy. Free-text and unrelated to a slab label. Must not be greater than 255 characters.

Example: "Longbox A / row 3"

bagged_atstring or null

Date the copy was bagged and boarded (YYYY-MM-DD). Must be a valid date.

Example: "2024-07-01"

personal_ratingnumber or null

The collector's own rating of this copy, in half stars from 0.5 to 5. Private to the copy: it is not a review and feeds no community average. One of: 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5.

Example: 4.5

tagsarray of strings

The collector's own labels for this copy. Private to the account — one user's tags are never visible to another. Must not be greater than 100 characters.

Example: ["key"]

comic_shop_idinteger or null

ID of the specific comic shop the copy was purchased from. Self-reported; independent of purchase_source. Must match an existing stored value.

Example: 412

acquisition_methodstring or null

How the comic was acquired. One of: purchase, trade, gift, inheritance, subscription, found, other.

Example: "purchase"

purchased_atstring or null

Date of purchase (YYYY-MM-DD). Must be a valid date.

Example: "2024-06-15"

storage_locationstring or null

Where the comic is stored. Must not be greater than 255 characters.

Example: "Long box #3"

is_signedboolean

Whether the comic is signed.

Example: false

signed_bystring or null

Name(s) of the creator(s) who signed the comic. Free-text. Comma-separate multiple signers. Must not be greater than 255 characters.

Example: "Stan Lee"

is_variantboolean

Whether this copy is a variant cover.

Example: false

variant_descriptionstring or null

Free-text description of the variant cover. Must not be greater than 500 characters.

Example: "Skottie Young baby variant"

variant_typestring or null

Variant classification (standard, cover_variant, retailer_exclusive, incentive_variant, ratio_variant, virgin_variant, etc.). One of: standard, cover_variant, retailer_exclusive, convention_exclusive, incentive_variant, ratio_variant, foil_variant, sketch_variant, virgin_variant, blank_variant, artist_variant, hologram_variant, glow_in_dark_variant, facsimile, reprint, other.

Example: "cover_variant"

gradedboolean

Whether the comic is professionally graded.

Example: false

grade_scorestring or null

Numeric grade score (e.g. 9.8). Must not be greater than 10 characters.

Example: "9.8"

grading_companystring or null

Grading company (CGC, CBCS, PGX, other, self_graded). One of: CGC, CBCS, PGX, other, self_graded.

Example: "CGC"

grading_numberstring or null

Grading certification number. Must not be greater than 50 characters.

Example: "1234567890"

label_typestring or null

Slab label tier (e.g. universal, signature_series, restored, qualified). One of: universal, signature_series, qualified, restored, cgcxjsa, standard, verified_signature, signed, conserved.

Example: "universal"

page_qualitystring or null

Interior page color quality from the slab label. One of: white, off_white_to_white, off_white, cream_to_off_white, light_tan, tan, brittle.

Example: "white"

grader_notesstring or null

Free-text notes printed on the slab label. Must not be greater than 2000 characters.

Example: "Marvel Value Stamp #16 intact"

print_numberstring or null

Which print this copy is (1st, 2nd, 3rd, … or other). One of: 1st, 2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th, 10th, other.

Example: "1st"

signature_witnessstring or null

Authentication of the signature (CGC, CBCS, JSA, PSA/DNA, witnessed_in_person, unwitnessed, other). One of: CGC, CBCS, JSA, PSA/DNA, witnessed_in_person, unwitnessed, other.

Example: "witnessed_in_person"

estimated_valuenumber or null

Current estimated value in dollars. Must be at least 0. Must not be greater than 999999.99.

Example: 25

for_saleboolean

Whether the item is for sale.

Example: false

statusstring

Whether the copy is owned, for_sale, or sold. A sold copy keeps its record but leaves the collection totals. One of: owned, for_sale, sold.

Example: "sold"

sold_atstring or null

Date the copy was sold. Must be a valid date.

Example: "2026-08-14"

price_soldnumber or null

What the copy sold for, in dollars. Must be at least 0. Must not be greater than 99999999.99.

Example: 40

for_tradeboolean

Whether the item is available for trade.

Example: false

is_publicboolean

Whether this collection item is publicly visible. Defaults to true.

Example: true

Responses

201

Added

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

dataobjectrequired
data.idintegerrequired

Example: 1001

data.user_idintegerrequired

Example: 42

data.collectable_typestringrequired

Example: "Issue"

data.collectable_idintegerrequired

Example: 5432

data.variant_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 789

data.conditionstring or nullrequired

Example: "NM"

data.purchased_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.notesstring or null

Left out for a read:showcase token.

Example: "First print"

data.formatstring or nullrequired

Example: "single"

data.storage_locationstring or null

Left out for a read:showcase token.

Example: "Long box 3"

data.price_paidstring or null

Left out for a read:showcase token.

Example: "3.99"

data.is_variantboolean or nullrequired
data.variant_descriptionstring or nullrequired

Example: "Cover B"

data.variant_typestring or nullrequired

Example: "cover"

data.gradedboolean or nullrequired
data.grade_scorestring or nullrequired

Example: "9.8"

data.grading_companystring or nullrequired

Example: "CGC"

data.grading_numberstring or nullrequired

Example: "1234567001"

data.label_typestring or nullrequired

Example: "universal"

data.page_qualitystring or nullrequired

Example: "white"

data.grader_notesstring or null

Left out for a read:showcase token.

Example: "Light spine stress"

data.purchase_sourcestring or null

Left out for a read:showcase token.

Example: "lcs"

data.comic_shop_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 17

data.comic_shopobject

The shop the copy came from, while it is listed; left out otherwise and for a read:showcase token.

data.comic_shop.idintegerrequired

Example: 17

data.comic_shop.namestring or nullrequired

Example: "Comic Corner"

data.comic_shop.slugstring or nullrequired

Example: "comic-corner"

data.comic_shop.citystring or nullrequired

Example: "Portland"

data.comic_shop.state_provincestring or nullrequired

Example: "OR"

data.acquisition_methodstring or null

Left out for a read:showcase token.

Example: "purchased"

data.purchase_storestring or null

Left out for a read:showcase token.

Example: "Comic Corner"

data.custom_labelstring or null

Left out for a read:showcase token.

Example: "Keys"

data.bagged_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.personal_ratingnumber or string or nullrequired

As sent on a write: a number, or text.

Example: 4.5

data.tagsarray of strings

Left out for a read:showcase token.

Example: ["keys"]

data.loanobject or null

Left out for a read:showcase token.

data.loan.idintegerrequired

Example: 3

data.loan.loaned_tostring or nullrequired

Example: "Sam"

data.loan.loaned_atstring or nullrequired

Example: "2024-01-15"

data.loan.due_atstring or nullrequired

Example: "2024-02-15"

data.loan.is_overduebooleanrequired
data.loan.days_until_dueinteger or nullrequired

Example: 12

data.is_signedboolean or nullrequired
data.signed_bystring or nullrequired

Example: "Stan Lee"

data.signature_witnessstring or nullrequired

Example: "CGC"

data.signature_authenticatedbooleanrequired
data.is_cgc_ssbooleanrequired
data.print_numberstring or nullrequired

Example: "1"

data.estimated_valuestring or null

Left out for a read:showcase token.

Example: "125.00"

data.value_last_updatedstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.statusstring or nullrequired

owned, for_sale or sold.

Example: "owned"

data.for_saleboolean or nullrequired
data.for_tradeboolean or nullrequired
data.sold_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.price_soldstring or null

Left out for a read:showcase token.

Example: "150.00"

data.is_publicboolean or nullrequired
data.cover_scan_urlstring or nullrequired

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

data.cover_scan_url_lgstring or nullrequired

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

data.cover_scan_uploaded_atstring or nullrequired

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

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.collectableobject or nullrequired

The issue.

data.collectable.idintegerrequired

Example: 5432

data.collectable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data.collectable.series_idinteger or nullrequired

Example: 123

data.collectable.issue_numberstring or nullrequired

Example: "1"

data.collectable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data.collectable.cover_datestring or nullrequired

Example: "2018-09-01"

data.collectable.release_datestring or nullrequired

Example: "2018-07-11"

data.collectable.foc_datestring or nullrequired

Example: "2018-06-18"

data.collectable.is_unreleasedbooleanrequired
data.collectable.cover_urlstring or nullrequired

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

data.collectable.imagesobject or nullrequired
data.collectable.images.thumbstring

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

data.collectable.images.cover_smstring

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

data.collectable.images.cover_mdstring

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

data.collectable.images.cover_lgstring

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

data.collectable.is_reprintbooleanrequired
data.collectable.content_rating_labelstring or nullrequired

Example: "Teen"

data.collectable.min_ageinteger or nullrequired

Example: 13

data.collectable.is_nsfwbooleanrequired
data.collectable.average_ratingnumber or nullrequired

Example: 4.5

data.collectable.name_i18nobjectrequired

The name in each language, keyed by BCP 47 tag (trimmed by ?languages=).

data.collectable.seriesobject or null
data.collectable.series.idintegerrequired

Example: 123

data.collectable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.collectable.series.slugstring or nullrequired

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

data.collectable.series.start_yearinteger or nullrequired

Example: 2018

data.collectable.series.end_yearinteger or nullrequired

Example: 2022

data.collectable.series.volume_numberinteger or nullrequired

Example: 5

data.collectable.series.publication_typestring or nullrequired

Example: "regular_series"

data.collectable.series.formatstring or nullrequired

Example: "Standard"

data.collectable.series.cached_issues_countinteger or nullrequired

Example: 93

data.collectable.series.cover_urlstring or nullrequired

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

data.collectable.series.imagesobject or nullrequired
data.collectable.series.images.cover_smstring

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

data.collectable.series.images.cover_mdstring

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

data.collectable.series.images.cover_lgstring

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

data.collectable.series.publisher_namestring or nullrequired

Example: "Marvel"

was_on_wishlistbooleanrequired

Example: true

follow_upobjectrequired
follow_up.promptbooleanrequired

The member asked to be prompted, and there is something to offer.

Example: true

follow_up.can_mark_readbooleanrequired

Example: true

follow_up.can_reviewbooleanrequired

Example: true

follow_up.has_reviewbooleanrequired

Example: false

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:collection nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID.

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"
}
422

A field the rules refuse, a variant of another issue, or an issue not released yet.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 POST \
  'https://versedb.com/api/v1/issues/5432/collection' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "variant_id": 42,
  "condition": "NM",
  "notes": "First print, great condition",
  "price_paid": 3.99,
  "format": "standard",
  "purchase_source": "comic_shop",
  "purchase_store": "Third Eye Comics",
  "custom_label": "Longbox A / row 3",
  "bagged_at": "2024-07-01",
  "personal_rating": 4.5,
  "tags": [
    "key"
  ],
  "comic_shop_id": 412,
  "acquisition_method": "purchase",
  "purchased_at": "2024-06-15",
  "storage_location": "Long box #3",
  "is_signed": false,
  "signed_by": "Stan Lee",
  "is_variant": false,
  "variant_description": "Skottie Young baby variant",
  "variant_type": "cover_variant",
  "graded": false,
  "grade_score": "9.8",
  "grading_company": "CGC",
  "grading_number": "1234567890",
  "label_type": "universal",
  "page_quality": "white",
  "grader_notes": "Marvel Value Stamp #16 intact",
  "print_number": "1st",
  "signature_witness": "witnessed_in_person",
  "estimated_value": 25,
  "for_sale": false,
  "status": "sold",
  "sold_at": "2026-08-14",
  "price_sold": 40,
  "for_trade": false,
  "is_public": true
}'

Example response 201

{
  "data": {
    "id": 1001,
    "user_id": 42,
    "collectable_type": "Issue",
    "collectable_id": 5432,
    "variant_id": 789,
    "condition": "NM",
    "purchased_at": "2024-01-15T00:00:00.000000Z",
    "notes": "First print",
    "format": "single",
    "storage_location": "Long box 3",
    "price_paid": "3.99",
    "variant_description": "Cover B",
    "variant_type": "cover",
    "grade_score": "9.8",
    "grading_company": "CGC",
    "grading_number": "1234567001",
    "label_type": "universal",
    "page_quality": "white",
    "grader_notes": "Light spine stress",
    "purchase_source": "lcs",
    "comic_shop_id": 17,
    "comic_shop": {
      "id": 17,
      "name": "Comic Corner",
      "slug": "comic-corner",
      "city": "Portland",
      "state_province": "OR"
    },
    "acquisition_method": "purchased",
    "purchase_store": "Comic Corner",
    "custom_label": "Keys",
    "bagged_at": "2024-01-15T00:00:00.000000Z",
    "personal_rating": 4.5,
    "tags": [
      "keys"
    ],
    "loan": {
      "id": 3,
      "loaned_to": "Sam",
      "loaned_at": "2024-01-15",
      "due_at": "2024-02-15",
      "days_until_due": 12
    },
    "signed_by": "Stan Lee",
    "signature_witness": "CGC",
    "print_number": "1",
    "estimated_value": "125.00",
    "value_last_updated": "2024-01-15T00:00:00.000000Z",
    "status": "owned",
    "sold_at": "2024-01-15T00:00:00.000000Z",
    "price_sold": "150.00",
    "cover_scan_url": "https://...-cover_md.webp",
    "cover_scan_url_lg": "https://...-cover_lg.webp",
    "cover_scan_uploaded_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "collectable": {
      "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": {
        "en": "Library One"
      },
      "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"
      }
    }
  },
  "was_on_wishlist": true,
  "follow_up": {
    "prompt": true,
    "can_mark_read": true,
    "can_review": true,
    "has_review": false
  }
}

Update collection item.

PATCH/api/v1/issues/{issue_id}/collection
Requires a token

Updates one of the user's copies of the issue: the copy collection_item_id names (query or body), else the oldest copy (of the query's variant_id cover when one is sent). Only the fields sent change; tags replaces the copy's tags. is_read and read_at set the issue's read status too.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Query parameters

variant_idinteger

Specific variant ID to update (when user has multiple entries).

Example: 789

collection_item_idinteger

Specific collection item ID to update.

Example: 1001

Request body application/json

variant_idinteger or null

Link to a specific issue variant. Must belong to the issue. Must match an existing stored value.

Example: 42

conditionstring or null

Comic condition grade (CGC scale). One of: MT, NM/MT, NM+, NM, NM-, VF/NM, VF+, VF, VF-, F/VF, F+, F, F-, VG/F, VG+, VG, VG-, G/VG, G, FR, PR.

Example: "NM"

notesstring or null

User notes about this copy. Must not be greater than 1000 characters.

Example: "First print, great condition"

price_paidnumber or null

Purchase price in dollars. Must be at least 0. Must not be greater than 999999.99.

Example: 3.99

formatstring or null

Physical format of the copy. One of: standard, trade_paperback, hardcover, omnibus, deluxe_edition, annual, graphic_novel, digital, treasury, magazine, prestige, digest, other.

Example: "standard"

purchase_sourcestring or null

Where the comic was purchased. One of: comic_shop, online_retailer, auction, convention, private_seller, subscription, digital_platform, second_hand_store, inheritance, gift, trade, other.

Example: "comic_shop"

purchase_storestring or null

Name of the store the copy was bought from, as free text. Use comic_shop_id instead where the shop is one VerseDB catalogs. Must not be greater than 255 characters.

Example: "Third Eye Comics"

custom_labelstring or null

The collector's own label for this copy. Free-text and unrelated to a slab label. Must not be greater than 255 characters.

Example: "Longbox A / row 3"

bagged_atstring or null

Date the copy was bagged and boarded (YYYY-MM-DD). Must be a valid date.

Example: "2024-07-01"

personal_ratingnumber or null

The collector's own rating of this copy, in half stars from 0.5 to 5. Private to the copy: it is not a review and feeds no community average. One of: 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5.

Example: 4.5

tagsarray of strings

The collector's own labels for this copy. Private to the account — one user's tags are never visible to another. Must not be greater than 100 characters.

Example: ["key"]

comic_shop_idinteger or null

ID of the specific comic shop the copy was purchased from. Self-reported; independent of purchase_source. Must match an existing stored value.

Example: 412

acquisition_methodstring or null

How the comic was acquired. One of: purchase, trade, gift, inheritance, subscription, found, other.

Example: "purchase"

purchased_atstring or null

Date of purchase (YYYY-MM-DD). Must be a valid date.

Example: "2024-06-15"

storage_locationstring or null

Where the comic is stored. Must not be greater than 255 characters.

Example: "Long box #3"

is_signedboolean

Whether the comic is signed.

Example: false

signed_bystring or null

Name(s) of the creator(s) who signed the comic. Free-text. Comma-separate multiple signers. Must not be greater than 255 characters.

Example: "Stan Lee"

is_variantboolean

Whether this copy is a variant cover.

Example: false

variant_descriptionstring or null

Free-text description of the variant cover. Must not be greater than 500 characters.

Example: "Skottie Young baby variant"

variant_typestring or null

Variant classification (standard, cover_variant, retailer_exclusive, incentive_variant, ratio_variant, virgin_variant, etc.). One of: standard, cover_variant, retailer_exclusive, convention_exclusive, incentive_variant, ratio_variant, foil_variant, sketch_variant, virgin_variant, blank_variant, artist_variant, hologram_variant, glow_in_dark_variant, facsimile, reprint, other.

Example: "cover_variant"

gradedboolean

Whether the comic is professionally graded.

Example: false

grade_scorestring or null

Numeric grade score (e.g. 9.8). Must not be greater than 10 characters.

Example: "9.8"

grading_companystring or null

Grading company (CGC, CBCS, PGX, other, self_graded). One of: CGC, CBCS, PGX, other, self_graded.

Example: "CGC"

grading_numberstring or null

Grading certification number. Must not be greater than 50 characters.

Example: "1234567890"

label_typestring or null

Slab label tier (e.g. universal, signature_series, restored, qualified). One of: universal, signature_series, qualified, restored, cgcxjsa, standard, verified_signature, signed, conserved.

Example: "universal"

page_qualitystring or null

Interior page color quality from the slab label. One of: white, off_white_to_white, off_white, cream_to_off_white, light_tan, tan, brittle.

Example: "white"

grader_notesstring or null

Free-text notes printed on the slab label. Must not be greater than 2000 characters.

Example: "Marvel Value Stamp #16 intact"

print_numberstring or null

Which print this copy is (1st, 2nd, 3rd, … or other). One of: 1st, 2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th, 10th, other.

Example: "1st"

signature_witnessstring or null

Authentication of the signature (CGC, CBCS, JSA, PSA/DNA, witnessed_in_person, unwitnessed, other). One of: CGC, CBCS, JSA, PSA/DNA, witnessed_in_person, unwitnessed, other.

Example: "witnessed_in_person"

estimated_valuenumber or null

Current estimated value in dollars. Must be at least 0. Must not be greater than 999999.99.

Example: 25

for_saleboolean

Whether the item is for sale.

Example: false

statusstring

Whether the copy is owned, for_sale, or sold. A sold copy keeps its record but leaves the collection totals. One of: owned, for_sale, sold.

Example: "sold"

sold_atstring or null

Date the copy was sold. Must be a valid date.

Example: "2026-08-14"

price_soldnumber or null

What the copy sold for, in dollars. Must be at least 0. Must not be greater than 99999999.99.

Example: 40

for_tradeboolean

Whether the item is available for trade.

Example: false

is_publicboolean

Whether this collection item is publicly visible.

Example: true

is_readboolean

Whether the issue has been read.

Example: true

read_atstring or null

When the issue was read (YYYY-MM-DD). Cannot be in the future. Must be a valid date. Must be a date before or equal to today.

Example: "2024-06-15"

Responses

200

Success

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

dataobjectrequired
data.idintegerrequired

Example: 1001

data.user_idintegerrequired

Example: 42

data.collectable_typestringrequired

Example: "Issue"

data.collectable_idintegerrequired

Example: 5432

data.variant_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 789

data.conditionstring or nullrequired

Example: "NM"

data.purchased_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.notesstring or null

Left out for a read:showcase token.

Example: "First print"

data.formatstring or nullrequired

Example: "single"

data.storage_locationstring or null

Left out for a read:showcase token.

Example: "Long box 3"

data.price_paidstring or null

Left out for a read:showcase token.

Example: "3.99"

data.is_variantboolean or nullrequired
data.variant_descriptionstring or nullrequired

Example: "Cover B"

data.variant_typestring or nullrequired

Example: "cover"

data.gradedboolean or nullrequired
data.grade_scorestring or nullrequired

Example: "9.8"

data.grading_companystring or nullrequired

Example: "CGC"

data.grading_numberstring or nullrequired

Example: "1234567001"

data.label_typestring or nullrequired

Example: "universal"

data.page_qualitystring or nullrequired

Example: "white"

data.grader_notesstring or null

Left out for a read:showcase token.

Example: "Light spine stress"

data.purchase_sourcestring or null

Left out for a read:showcase token.

Example: "lcs"

data.comic_shop_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 17

data.comic_shopobject

The shop the copy came from, while it is listed; left out otherwise and for a read:showcase token.

data.comic_shop.idintegerrequired

Example: 17

data.comic_shop.namestring or nullrequired

Example: "Comic Corner"

data.comic_shop.slugstring or nullrequired

Example: "comic-corner"

data.comic_shop.citystring or nullrequired

Example: "Portland"

data.comic_shop.state_provincestring or nullrequired

Example: "OR"

data.acquisition_methodstring or null

Left out for a read:showcase token.

Example: "purchased"

data.purchase_storestring or null

Left out for a read:showcase token.

Example: "Comic Corner"

data.custom_labelstring or null

Left out for a read:showcase token.

Example: "Keys"

data.bagged_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.personal_ratingnumber or string or nullrequired

As sent on a write: a number, or text.

Example: 4.5

data.tagsarray of strings

Left out for a read:showcase token.

Example: ["keys"]

data.loanobject or null

Left out for a read:showcase token.

data.loan.idintegerrequired

Example: 3

data.loan.loaned_tostring or nullrequired

Example: "Sam"

data.loan.loaned_atstring or nullrequired

Example: "2024-01-15"

data.loan.due_atstring or nullrequired

Example: "2024-02-15"

data.loan.is_overduebooleanrequired
data.loan.days_until_dueinteger or nullrequired

Example: 12

data.is_signedboolean or nullrequired
data.signed_bystring or nullrequired

Example: "Stan Lee"

data.signature_witnessstring or nullrequired

Example: "CGC"

data.signature_authenticatedbooleanrequired
data.is_cgc_ssbooleanrequired
data.print_numberstring or nullrequired

Example: "1"

data.estimated_valuestring or null

Left out for a read:showcase token.

Example: "125.00"

data.value_last_updatedstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.statusstring or nullrequired

owned, for_sale or sold.

Example: "owned"

data.for_saleboolean or nullrequired
data.for_tradeboolean or nullrequired
data.sold_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.price_soldstring or null

Left out for a read:showcase token.

Example: "150.00"

data.is_publicboolean or nullrequired
data.cover_scan_urlstring or nullrequired

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

data.cover_scan_url_lgstring or nullrequired

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

data.cover_scan_uploaded_atstring or nullrequired

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

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.collectableobject or nullrequired

The issue.

data.collectable.idintegerrequired

Example: 5432

data.collectable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data.collectable.series_idinteger or nullrequired

Example: 123

data.collectable.issue_numberstring or nullrequired

Example: "1"

data.collectable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data.collectable.cover_datestring or nullrequired

Example: "2018-09-01"

data.collectable.release_datestring or nullrequired

Example: "2018-07-11"

data.collectable.foc_datestring or nullrequired

Example: "2018-06-18"

data.collectable.is_unreleasedbooleanrequired
data.collectable.cover_urlstring or nullrequired

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

data.collectable.imagesobject or nullrequired
data.collectable.images.thumbstring

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

data.collectable.images.cover_smstring

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

data.collectable.images.cover_mdstring

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

data.collectable.images.cover_lgstring

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

data.collectable.is_reprintbooleanrequired
data.collectable.content_rating_labelstring or nullrequired

Example: "Teen"

data.collectable.min_ageinteger or nullrequired

Example: 13

data.collectable.is_nsfwbooleanrequired
data.collectable.average_ratingnumber or nullrequired

Example: 4.5

data.collectable.name_i18nobjectrequired

The name in each language, keyed by BCP 47 tag (trimmed by ?languages=).

data.collectable.seriesobject or null
data.collectable.series.idintegerrequired

Example: 123

data.collectable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.collectable.series.slugstring or nullrequired

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

data.collectable.series.start_yearinteger or nullrequired

Example: 2018

data.collectable.series.end_yearinteger or nullrequired

Example: 2022

data.collectable.series.volume_numberinteger or nullrequired

Example: 5

data.collectable.series.publication_typestring or nullrequired

Example: "regular_series"

data.collectable.series.formatstring or nullrequired

Example: "Standard"

data.collectable.series.cached_issues_countinteger or nullrequired

Example: 93

data.collectable.series.cover_urlstring or nullrequired

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

data.collectable.series.imagesobject or nullrequired
data.collectable.series.images.cover_smstring

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

data.collectable.series.images.cover_mdstring

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

data.collectable.series.images.cover_lgstring

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

data.collectable.series.publisher_namestring or nullrequired

Example: "Marvel"

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:collection nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID (message), or the user holds no such copy of it (error).

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"
}
422

A field the rules refuse, a variant of another issue, or is_read on an issue not released yet (the copy is still updated).

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 PATCH \
  'https://versedb.com/api/v1/issues/5432/collection' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "variant_id": 42,
  "condition": "NM",
  "notes": "First print, great condition",
  "price_paid": 3.99,
  "format": "standard",
  "purchase_source": "comic_shop",
  "purchase_store": "Third Eye Comics",
  "custom_label": "Longbox A / row 3",
  "bagged_at": "2024-07-01",
  "personal_rating": 4.5,
  "tags": [
    "key"
  ],
  "comic_shop_id": 412,
  "acquisition_method": "purchase",
  "purchased_at": "2024-06-15",
  "storage_location": "Long box #3",
  "is_signed": false,
  "signed_by": "Stan Lee",
  "is_variant": false,
  "variant_description": "Skottie Young baby variant",
  "variant_type": "cover_variant",
  "graded": false,
  "grade_score": "9.8",
  "grading_company": "CGC",
  "grading_number": "1234567890",
  "label_type": "universal",
  "page_quality": "white",
  "grader_notes": "Marvel Value Stamp #16 intact",
  "print_number": "1st",
  "signature_witness": "witnessed_in_person",
  "estimated_value": 25,
  "for_sale": false,
  "status": "sold",
  "sold_at": "2026-08-14",
  "price_sold": 40,
  "for_trade": false,
  "is_public": true,
  "is_read": true,
  "read_at": "2024-06-15"
}'

Example response 200

{
  "data": {
    "id": 1001,
    "user_id": 42,
    "collectable_type": "Issue",
    "collectable_id": 5432,
    "variant_id": 789,
    "condition": "NM",
    "purchased_at": "2024-01-15T00:00:00.000000Z",
    "notes": "First print",
    "format": "single",
    "storage_location": "Long box 3",
    "price_paid": "3.99",
    "variant_description": "Cover B",
    "variant_type": "cover",
    "grade_score": "9.8",
    "grading_company": "CGC",
    "grading_number": "1234567001",
    "label_type": "universal",
    "page_quality": "white",
    "grader_notes": "Light spine stress",
    "purchase_source": "lcs",
    "comic_shop_id": 17,
    "comic_shop": {
      "id": 17,
      "name": "Comic Corner",
      "slug": "comic-corner",
      "city": "Portland",
      "state_province": "OR"
    },
    "acquisition_method": "purchased",
    "purchase_store": "Comic Corner",
    "custom_label": "Keys",
    "bagged_at": "2024-01-15T00:00:00.000000Z",
    "personal_rating": 4.5,
    "tags": [
      "keys"
    ],
    "loan": {
      "id": 3,
      "loaned_to": "Sam",
      "loaned_at": "2024-01-15",
      "due_at": "2024-02-15",
      "days_until_due": 12
    },
    "signed_by": "Stan Lee",
    "signature_witness": "CGC",
    "print_number": "1",
    "estimated_value": "125.00",
    "value_last_updated": "2024-01-15T00:00:00.000000Z",
    "status": "owned",
    "sold_at": "2024-01-15T00:00:00.000000Z",
    "price_sold": "150.00",
    "cover_scan_url": "https://...-cover_md.webp",
    "cover_scan_url_lg": "https://...-cover_lg.webp",
    "cover_scan_uploaded_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "collectable": {
      "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": {
        "en": "Library One"
      },
      "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"
      }
    }
  }
}

Remove issue from collection.

DELETE/api/v1/issues/{issue_id}/collection
Requires a token

Removes one of the user's copies of the issue: the copy collection_item_id names, else the oldest copy (of variant_id's cover when one is sent). Each may come in the query or the body.

Path parameters

issue_idintegerrequired

The issue ID.

Example: 5432

Query parameters

variant_idinteger

Specific variant ID to remove (optional).

Example: 789

collection_item_idinteger

Specific collection item ID to remove (optional).

Example: 1001

Responses

204

Removed

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

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:collection nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No live issue has this ID (message), or the user holds no such copy of it (error).

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"
}
422

A variant that does not exist, or a collection item ID that is not an integer.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 DELETE \
  'https://versedb.com/api/v1/issues/5432/collection' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Lend a copy out.

POST/api/v1/user/collections/{collection_item_id}/loan
Requires a token

Records that one of the user's copies is out on loan. A copy already out is a 409 rather than a replacement: mark it returned, then lend it again.

Path parameters

collection_item_idintegerrequired

The collection item ID.

Example: 1001

Request body application/json

loaned_tostringrequired

Who has the comic. Free text: the borrower does not need a VerseDB account.

Example: "Dan from the shop"

loaned_atstring or null

The day it left (YYYY-MM-DD). Defaults to today.

Example: "2026-09-01"

due_atstring or null

When it is due back (YYYY-MM-DD), on or after loaned_at. Omit for an open-ended loan.

Example: "2026-10-01"

notesstring or null

Anything worth recording about the loan.

Example: "Lent at the Saturday meetup"

Responses

200

Lent

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

dataobjectrequired
data.idintegerrequired

Example: 1001

data.user_idintegerrequired

Example: 42

data.collectable_typestringrequired

Example: "Issue"

data.collectable_idintegerrequired

Example: 5432

data.variant_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 789

data.conditionstring or nullrequired

Example: "NM"

data.purchased_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.notesstring or null

Left out for a read:showcase token.

Example: "First print"

data.formatstring or nullrequired

Example: "single"

data.storage_locationstring or null

Left out for a read:showcase token.

Example: "Long box 3"

data.price_paidstring or null

Left out for a read:showcase token.

Example: "3.99"

data.is_variantboolean or nullrequired
data.variant_descriptionstring or nullrequired

Example: "Cover B"

data.variant_typestring or nullrequired

Example: "cover"

data.gradedboolean or nullrequired
data.grade_scorestring or nullrequired

Example: "9.8"

data.grading_companystring or nullrequired

Example: "CGC"

data.grading_numberstring or nullrequired

Example: "1234567001"

data.label_typestring or nullrequired

Example: "universal"

data.page_qualitystring or nullrequired

Example: "white"

data.grader_notesstring or null

Left out for a read:showcase token.

Example: "Light spine stress"

data.purchase_sourcestring or null

Left out for a read:showcase token.

Example: "lcs"

data.comic_shop_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 17

data.comic_shopobject

The shop the copy came from, while it is listed; left out otherwise and for a read:showcase token.

data.comic_shop.idintegerrequired

Example: 17

data.comic_shop.namestring or nullrequired

Example: "Comic Corner"

data.comic_shop.slugstring or nullrequired

Example: "comic-corner"

data.comic_shop.citystring or nullrequired

Example: "Portland"

data.comic_shop.state_provincestring or nullrequired

Example: "OR"

data.acquisition_methodstring or null

Left out for a read:showcase token.

Example: "purchased"

data.purchase_storestring or null

Left out for a read:showcase token.

Example: "Comic Corner"

data.custom_labelstring or null

Left out for a read:showcase token.

Example: "Keys"

data.bagged_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.personal_ratingnumber or string or nullrequired

As sent on a write: a number, or text.

Example: 4.5

data.tagsarray of strings

Left out for a read:showcase token.

Example: ["keys"]

data.loanobject or null

Left out for a read:showcase token.

data.loan.idintegerrequired

Example: 3

data.loan.loaned_tostring or nullrequired

Example: "Sam"

data.loan.loaned_atstring or nullrequired

Example: "2024-01-15"

data.loan.due_atstring or nullrequired

Example: "2024-02-15"

data.loan.is_overduebooleanrequired
data.loan.days_until_dueinteger or nullrequired

Example: 12

data.is_signedboolean or nullrequired
data.signed_bystring or nullrequired

Example: "Stan Lee"

data.signature_witnessstring or nullrequired

Example: "CGC"

data.signature_authenticatedbooleanrequired
data.is_cgc_ssbooleanrequired
data.print_numberstring or nullrequired

Example: "1"

data.estimated_valuestring or null

Left out for a read:showcase token.

Example: "125.00"

data.value_last_updatedstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.statusstring or nullrequired

owned, for_sale or sold.

Example: "owned"

data.for_saleboolean or nullrequired
data.for_tradeboolean or nullrequired
data.sold_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.price_soldstring or null

Left out for a read:showcase token.

Example: "150.00"

data.is_publicboolean or nullrequired
data.cover_scan_urlstring or nullrequired

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

data.cover_scan_url_lgstring or nullrequired

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

data.cover_scan_uploaded_atstring or nullrequired

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

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.collectableobject or nullrequired

The issue.

data.collectable.idintegerrequired

Example: 5432

data.collectable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data.collectable.series_idinteger or nullrequired

Example: 123

data.collectable.issue_numberstring or nullrequired

Example: "1"

data.collectable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data.collectable.cover_datestring or nullrequired

Example: "2018-09-01"

data.collectable.release_datestring or nullrequired

Example: "2018-07-11"

data.collectable.foc_datestring or nullrequired

Example: "2018-06-18"

data.collectable.is_unreleasedbooleanrequired
data.collectable.cover_urlstring or nullrequired

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

data.collectable.imagesobject or nullrequired
data.collectable.images.thumbstring

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

data.collectable.images.cover_smstring

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

data.collectable.images.cover_mdstring

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

data.collectable.images.cover_lgstring

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

data.collectable.is_reprintbooleanrequired
data.collectable.content_rating_labelstring or nullrequired

Example: "Teen"

data.collectable.min_ageinteger or nullrequired

Example: 13

data.collectable.is_nsfwbooleanrequired
data.collectable.average_ratingnumber or nullrequired

Example: 4.5

data.collectable.name_i18nobjectrequired

The name in each language, keyed by BCP 47 tag (trimmed by ?languages=).

data.collectable.seriesobject or null
data.collectable.series.idintegerrequired

Example: 123

data.collectable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.collectable.series.slugstring or nullrequired

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

data.collectable.series.start_yearinteger or nullrequired

Example: 2018

data.collectable.series.end_yearinteger or nullrequired

Example: 2022

data.collectable.series.volume_numberinteger or nullrequired

Example: 5

data.collectable.series.publication_typestring or nullrequired

Example: "regular_series"

data.collectable.series.formatstring or nullrequired

Example: "Standard"

data.collectable.series.cached_issues_countinteger or nullrequired

Example: 93

data.collectable.series.cover_urlstring or nullrequired

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

data.collectable.series.imagesobject or nullrequired
data.collectable.series.images.cover_smstring

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

data.collectable.series.images.cover_mdstring

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

data.collectable.series.images.cover_lgstring

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

data.collectable.series.publisher_namestring or nullrequired

Example: "Marvel"

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:collection nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No collection item has this ID, or the user does not own it (Collection item not found.).

messagestringrequired

Example: "No query results for model [App\\Models\\UserCollection] 1001"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserCollection] 1001"
}
409

The copy is already on loan.

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

messagestringrequired

Example: "This copy is already on loan. Mark it returned before lending it again."

Example body, from the documented examples

{
  "message": "This copy is already on loan. Mark it returned before lending it again."
}
422

A field the rules refuse.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 POST \
  'https://versedb.com/api/v1/user/collections/1001/loan' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "loaned_to": "Dan from the shop",
  "loaned_at": "2026-09-01",
  "due_at": "2026-10-01",
  "notes": "Lent at the Saturday meetup"
}'

Example response 200

{
  "data": {
    "id": 1001,
    "user_id": 42,
    "collectable_type": "Issue",
    "collectable_id": 5432,
    "variant_id": 789,
    "condition": "NM",
    "purchased_at": "2024-01-15T00:00:00.000000Z",
    "notes": "First print",
    "format": "single",
    "storage_location": "Long box 3",
    "price_paid": "3.99",
    "variant_description": "Cover B",
    "variant_type": "cover",
    "grade_score": "9.8",
    "grading_company": "CGC",
    "grading_number": "1234567001",
    "label_type": "universal",
    "page_quality": "white",
    "grader_notes": "Light spine stress",
    "purchase_source": "lcs",
    "comic_shop_id": 17,
    "comic_shop": {
      "id": 17,
      "name": "Comic Corner",
      "slug": "comic-corner",
      "city": "Portland",
      "state_province": "OR"
    },
    "acquisition_method": "purchased",
    "purchase_store": "Comic Corner",
    "custom_label": "Keys",
    "bagged_at": "2024-01-15T00:00:00.000000Z",
    "personal_rating": 4.5,
    "tags": [
      "keys"
    ],
    "loan": {
      "id": 3,
      "loaned_to": "Sam",
      "loaned_at": "2024-01-15",
      "due_at": "2024-02-15",
      "days_until_due": 12
    },
    "signed_by": "Stan Lee",
    "signature_witness": "CGC",
    "print_number": "1",
    "estimated_value": "125.00",
    "value_last_updated": "2024-01-15T00:00:00.000000Z",
    "status": "owned",
    "sold_at": "2024-01-15T00:00:00.000000Z",
    "price_sold": "150.00",
    "cover_scan_url": "https://...-cover_md.webp",
    "cover_scan_url_lg": "https://...-cover_lg.webp",
    "cover_scan_uploaded_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "collectable": {
      "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": {
        "en": "Library One"
      },
      "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"
      }
    }
  }
}

Mark the copy's open loan returned.

DELETE/api/v1/user/collections/{collection_item_id}/loan
Requires a token

Closes the copy's open loan. A copy with no open loan is a 404, so a repeat call does not silently succeed.

Path parameters

collection_item_idintegerrequired

The collection item ID.

Example: 1001

Request body application/json

returned_atstring or null

The day it came back (YYYY-MM-DD). Defaults to today.

Example: "2026-09-20"

Responses

200

Returned

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

dataobjectrequired
data.idintegerrequired

Example: 1001

data.user_idintegerrequired

Example: 42

data.collectable_typestringrequired

Example: "Issue"

data.collectable_idintegerrequired

Example: 5432

data.variant_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 789

data.conditionstring or nullrequired

Example: "NM"

data.purchased_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.notesstring or null

Left out for a read:showcase token.

Example: "First print"

data.formatstring or nullrequired

Example: "single"

data.storage_locationstring or null

Left out for a read:showcase token.

Example: "Long box 3"

data.price_paidstring or null

Left out for a read:showcase token.

Example: "3.99"

data.is_variantboolean or nullrequired
data.variant_descriptionstring or nullrequired

Example: "Cover B"

data.variant_typestring or nullrequired

Example: "cover"

data.gradedboolean or nullrequired
data.grade_scorestring or nullrequired

Example: "9.8"

data.grading_companystring or nullrequired

Example: "CGC"

data.grading_numberstring or nullrequired

Example: "1234567001"

data.label_typestring or nullrequired

Example: "universal"

data.page_qualitystring or nullrequired

Example: "white"

data.grader_notesstring or null

Left out for a read:showcase token.

Example: "Light spine stress"

data.purchase_sourcestring or null

Left out for a read:showcase token.

Example: "lcs"

data.comic_shop_idinteger or string or nullrequired

As sent: a number, or digits as text.

Example: 17

data.comic_shopobject

The shop the copy came from, while it is listed; left out otherwise and for a read:showcase token.

data.comic_shop.idintegerrequired

Example: 17

data.comic_shop.namestring or nullrequired

Example: "Comic Corner"

data.comic_shop.slugstring or nullrequired

Example: "comic-corner"

data.comic_shop.citystring or nullrequired

Example: "Portland"

data.comic_shop.state_provincestring or nullrequired

Example: "OR"

data.acquisition_methodstring or null

Left out for a read:showcase token.

Example: "purchased"

data.purchase_storestring or null

Left out for a read:showcase token.

Example: "Comic Corner"

data.custom_labelstring or null

Left out for a read:showcase token.

Example: "Keys"

data.bagged_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.personal_ratingnumber or string or nullrequired

As sent on a write: a number, or text.

Example: 4.5

data.tagsarray of strings

Left out for a read:showcase token.

Example: ["keys"]

data.loanobject or null

Left out for a read:showcase token.

data.loan.idintegerrequired

Example: 3

data.loan.loaned_tostring or nullrequired

Example: "Sam"

data.loan.loaned_atstring or nullrequired

Example: "2024-01-15"

data.loan.due_atstring or nullrequired

Example: "2024-02-15"

data.loan.is_overduebooleanrequired
data.loan.days_until_dueinteger or nullrequired

Example: 12

data.is_signedboolean or nullrequired
data.signed_bystring or nullrequired

Example: "Stan Lee"

data.signature_witnessstring or nullrequired

Example: "CGC"

data.signature_authenticatedbooleanrequired
data.is_cgc_ssbooleanrequired
data.print_numberstring or nullrequired

Example: "1"

data.estimated_valuestring or null

Left out for a read:showcase token.

Example: "125.00"

data.value_last_updatedstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.statusstring or nullrequired

owned, for_sale or sold.

Example: "owned"

data.for_saleboolean or nullrequired
data.for_tradeboolean or nullrequired
data.sold_atstring or null

Left out for a read:showcase token.

Example: "2024-01-15T00:00:00.000000Z"

data.price_soldstring or null

Left out for a read:showcase token.

Example: "150.00"

data.is_publicboolean or nullrequired
data.cover_scan_urlstring or nullrequired

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

data.cover_scan_url_lgstring or nullrequired

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

data.cover_scan_uploaded_atstring or nullrequired

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

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.collectableobject or nullrequired

The issue.

data.collectable.idintegerrequired

Example: 5432

data.collectable.slugstring or nullrequired

Example: "amazing-spider-man-1"

data.collectable.series_idinteger or nullrequired

Example: 123

data.collectable.issue_numberstring or nullrequired

Example: "1"

data.collectable.namestring or nullrequired

Example: "The Chameleon Strikes!"

data.collectable.cover_datestring or nullrequired

Example: "2018-09-01"

data.collectable.release_datestring or nullrequired

Example: "2018-07-11"

data.collectable.foc_datestring or nullrequired

Example: "2018-06-18"

data.collectable.is_unreleasedbooleanrequired
data.collectable.cover_urlstring or nullrequired

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

data.collectable.imagesobject or nullrequired
data.collectable.images.thumbstring

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

data.collectable.images.cover_smstring

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

data.collectable.images.cover_mdstring

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

data.collectable.images.cover_lgstring

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

data.collectable.is_reprintbooleanrequired
data.collectable.content_rating_labelstring or nullrequired

Example: "Teen"

data.collectable.min_ageinteger or nullrequired

Example: 13

data.collectable.is_nsfwbooleanrequired
data.collectable.average_ratingnumber or nullrequired

Example: 4.5

data.collectable.name_i18nobjectrequired

The name in each language, keyed by BCP 47 tag (trimmed by ?languages=).

data.collectable.seriesobject or null
data.collectable.series.idintegerrequired

Example: 123

data.collectable.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data.collectable.series.slugstring or nullrequired

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

data.collectable.series.start_yearinteger or nullrequired

Example: 2018

data.collectable.series.end_yearinteger or nullrequired

Example: 2022

data.collectable.series.volume_numberinteger or nullrequired

Example: 5

data.collectable.series.publication_typestring or nullrequired

Example: "regular_series"

data.collectable.series.formatstring or nullrequired

Example: "Standard"

data.collectable.series.cached_issues_countinteger or nullrequired

Example: 93

data.collectable.series.cover_urlstring or nullrequired

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

data.collectable.series.imagesobject or nullrequired
data.collectable.series.images.cover_smstring

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

data.collectable.series.images.cover_mdstring

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

data.collectable.series.images.cover_lgstring

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

data.collectable.series.publisher_namestring or nullrequired

Example: "Marvel"

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token holds neither write:collection nor write:lists.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No collection item has this ID, the user does not own it, or it is not on loan.

messagestringrequired

Example: "This copy is not on loan."

Example body, from the documented examples

{
  "message": "This copy is not on loan."
}
422

A returned_at that is not a date.

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

messagestringrequired

Example: "The specified variant does not exist or does not belong to this issue."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The specified variant does not exist or does not belong to this issue.",
  "errors": {
    "variant_id": [
      "The specified variant does not exist or does not belong to this issue."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 DELETE \
  'https://versedb.com/api/v1/user/collections/1001/loan' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "returned_at": "2026-09-20"
}'

Example response 200

{
  "data": {
    "id": 1001,
    "user_id": 42,
    "collectable_type": "Issue",
    "collectable_id": 5432,
    "variant_id": 789,
    "condition": "NM",
    "purchased_at": "2024-01-15T00:00:00.000000Z",
    "notes": "First print",
    "format": "single",
    "storage_location": "Long box 3",
    "price_paid": "3.99",
    "variant_description": "Cover B",
    "variant_type": "cover",
    "grade_score": "9.8",
    "grading_company": "CGC",
    "grading_number": "1234567001",
    "label_type": "universal",
    "page_quality": "white",
    "grader_notes": "Light spine stress",
    "purchase_source": "lcs",
    "comic_shop_id": 17,
    "comic_shop": {
      "id": 17,
      "name": "Comic Corner",
      "slug": "comic-corner",
      "city": "Portland",
      "state_province": "OR"
    },
    "acquisition_method": "purchased",
    "purchase_store": "Comic Corner",
    "custom_label": "Keys",
    "bagged_at": "2024-01-15T00:00:00.000000Z",
    "personal_rating": 4.5,
    "tags": [
      "keys"
    ],
    "loan": {
      "id": 3,
      "loaned_to": "Sam",
      "loaned_at": "2024-01-15",
      "due_at": "2024-02-15",
      "days_until_due": 12
    },
    "signed_by": "Stan Lee",
    "signature_witness": "CGC",
    "print_number": "1",
    "estimated_value": "125.00",
    "value_last_updated": "2024-01-15T00:00:00.000000Z",
    "status": "owned",
    "sold_at": "2024-01-15T00:00:00.000000Z",
    "price_sold": "150.00",
    "cover_scan_url": "https://...-cover_md.webp",
    "cover_scan_url_lg": "https://...-cover_lg.webp",
    "cover_scan_uploaded_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z",
    "collectable": {
      "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": {
        "en": "Library One"
      },
      "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"
      }
    }
  }
}

List follows.

GET/api/v1/user/follows
Requires a token

Returns all entities the user is following (titles, characters, podcasts, etc.).

Query parameters

per_pageinteger

Items per page (max 100).

Example: 20

typestring

Only follows of this followable type (the morph alias, e.g. Title, Character, Creator, User).

Example: "Character"

qstring

Only follows whose followed entity matches this search (name; username for users).

Example: "spider"

Responses

200

Success

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

dataarray of objects
data[].idinteger

Example: 789

data[].followable_typestring

Example: "title"

data[].followable_idinteger

Example: 123

data[].followableobject
data[].followable.idinteger

Example: 123

data[].followable.namestring

Example: "Spider-Man"

data[].followable.cover_urlstring

Example: "..."

data[].created_atstring

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

metaobject
meta.current_pageinteger

Example: 1

meta.last_pageinteger

Example: 1

meta.per_pageinteger

Example: 20

meta.totalinteger

Example: 12

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
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/user/follows' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 789,
      "followable_type": "title",
      "followable_id": 123,
      "followable": {
        "id": 123,
        "name": "Spider-Man",
        "cover_url": "..."
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 12
  }
}

Check follow status.

GET/api/v1/follow/{type}/{id}/check
Requires a token

Reports whether the authenticated user currently follows the given entity.

Path parameters

typestringrequired

The content type (title, character, podcast, creator, publisher, team, story_arc, comic_shop, event, event_franchise, user).

Example: "title"

idintegerrequired

The ID of the content.

Example: 45

Responses

200

Success

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

is_followingboolean

Example: true

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
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/follow/title/45/check' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "is_following": true
}

Follow content.

POST/api/v1/follow
Requires a token

Follows a title, character, podcast, creator, publisher, team, story arc, comic shop, event, event franchise, or user.

Request body application/json

typestringrequired

The content type (title, character, podcast, creator, publisher, team, story_arc, comic_shop, event, event_franchise, user). An event_franchise is the recurring convention itself, so the follow covers every edition, including ones added later. Following an event that belongs to a franchise follows the franchise too, and unfollowing either clears both.

Example: "title"

idintegerrequired

The ID of the content to follow.

Example: 45

preferencesobject or null

Notification preferences.

preferences.email_notificationsboolean

Receive email notifications.

Example: true

preferences.push_notificationsboolean

Receive push notifications.

Example: false

Responses

200

Success

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

messagestring

Example: "Following title successfully"

is_followingboolean

Example: true

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

Refused

messagestring

Example: "This profile is private, so it cannot be followed."

codestring

Example: "private_profile"

is_followingboolean

Example: false

Example body, from the documented examples

{
  "message": "This profile is private, so it cannot be followed.",
  "code": "private_profile",
  "is_following": false
}
404

Not Found

messagestring

Example: "Title not found"

Example body, from the documented examples

{
  "message": "Title not found"
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 POST \
  'https://versedb.com/api/v1/follow' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "title",
  "id": 45,
  "preferences": {
    "email_notifications": true,
    "push_notifications": false
  }
}'

Example response 200

{
  "message": "Following title successfully",
  "is_following": true
}

Unfollow content.

DELETE/api/v1/follow/{type}/{id}
Requires a token

Stops following the given entity for the authenticated user.

Path parameters

typestringrequired

The content type (title, character, podcast, creator, publisher, team, story_arc, comic_shop, event, event_franchise, user).

Example: "title"

idintegerrequired

The ID of the followed content.

Example: 45

Responses

200

Success

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

messagestring

Example: "Unfollowed title successfully"

is_followingboolean

Example: false

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
404

Not Found

messagestring

Example: "Title not found"

Example body, from the documented examples

{
  "message": "Title not found"
}
429

Rate limit exceeded. This endpoint allows 150/hour (free) or 500/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 DELETE \
  'https://versedb.com/api/v1/follow/title/45' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "message": "Unfollowed title successfully",
  "is_following": false
}

Get activity feed.

GET/api/v1/user/activity
Requires a tokenDeprecated

Aggregates recent activity from collections, reads, follows, and reviews.

Query parameters

per_pageinteger

Number of results per page (max 100).

Example: 20

pageinteger

Page of results to return.

Example: 1

Responses

200

Success

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

dataarray of objects
data[].idstring

Example: "collection_9921"

data[].typestring

Example: "collection"

data[].actionstring

Example: "added_to_collection"

data[].created_atstring

Example: "2026-06-20T14:32:00+00:00"

data[].dataobject
data[].data.issue_idinteger

Example: 5432

data[].data.issue_namestring

Example: "Amazing Spider-Man #1"

data[].data.series_namestring

Example: "Amazing Spider-Man"

data[].data.series_start_yearinteger

Example: 2022

data[].data.cover_urlstring

Example: "https://r2.versedb.com/uploads/issues/asm-5432/asm-5432-cover_md.webp"

metaobject
meta.current_pageinteger

Example: 1

meta.per_pageinteger

Example: 20

meta.totalinteger

Example: 84

meta.last_pageinteger

Example: 5

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
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/user/activity' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": "collection_9921",
      "type": "collection",
      "action": "added_to_collection",
      "created_at": "2026-06-20T14:32:00+00:00",
      "data": {
        "issue_id": 5432,
        "issue_name": "Amazing Spider-Man #1",
        "series_name": "Amazing Spider-Man",
        "series_start_year": 2022,
        "cover_url": "https://r2.versedb.com/uploads/issues/asm-5432/asm-5432-cover_md.webp"
      }
    },
    {
      "id": "review_312",
      "type": "review",
      "action": "wrote_review",
      "created_at": "2026-06-19T09:10:00+00:00",
      "data": {
        "review_id": 312,
        "issue_id": 5410,
        "issue_name": "Batman #135",
        "series_name": "Batman",
        "series_start_year": 2016,
        "rating": 4.5,
        "content_preview": "A strong anniversary issue that pays off years of buildup...",
        "cover_url": "https://r2.versedb.com/uploads/issues/batman-5410/batman-5410-cover_md.webp"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 84,
    "last_page": 5
  }
}

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.