Skip to content
VerseDB

Cover Lookup

Identify a comic from a photo of its cover. The photo is matched by image against every cover in the catalog (issues and variants), and the answer is catalog ids. No cover image is stored, and none comes back beyond the cover URLs the issue resource already carries.

Look up an issue by cover photo.

POST/api/v1/lookup/cover
Requires a token

Upload a photo of a comic cover (bare, bagged or slabbed) as image. clear_match true means the image match is sure of the issue: issue_id is it, and variant_id is the cover when the match also settled which of the issue's covers it is (null is the issue's own cover, or a cover it could not tell apart from a same-art sibling such as a newsstand edition). clear_match false means the image was not sure: issue_id is null and candidates lists up to five issues it could be, best first, each at its best-scoring cover. Only the image is compared; no text is read off the cover, so a slab label's grade is not returned. Requires the read:public scope. Rate limited separately from catalog reads: 5/min and 100/day, or 15/min and 500/day on PRO.

Request body multipart/form-data

imagefilerequired

A photo of the comic cover: JPEG, PNG, GIF, BMP or WebP, up to 5MB. Must be an image. Must not be greater than 5120 kilobytes.

Responses

200

Success.

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

matched_bystringrequired

Always image: the answer comes from the image match.

Example: "image"

clear_matchbooleanrequired

Whether the image match is sure of the issue.

Example: true

issue_idinteger or nullrequired

The matched issue when clear_match is true, otherwise null.

Example: 5432

variant_idinteger or nullrequired

The matched variant cover when the match settled one, otherwise null.

Example: 789

candidatesarray of objectsrequired

Best first: the matched issue alone on a clear match, otherwise up to five possibilities.

candidates[].issue_idintegerrequired

The candidate issue.

Example: 5432

candidates[].variant_idinteger or nullrequired

The candidate's best-scoring variant cover; null is the issue's own cover.

Example: 789

candidates[].issueobjectrequired

The issue, as GET /api/v1/issues returns it with include=series.

candidates[].issue.idintegerrequired

Example: 5432

candidates[].issue.slugstring or nullrequired

Example: "amazing-spider-man-1"

candidates[].issue.series_idinteger or nullrequired

Example: 123

candidates[].issue.issue_numberstring or nullrequired

Example: "1"

candidates[].issue.namestring or nullrequired

Example: "The Chameleon Strikes!"

candidates[].issue.cover_datestring or nullrequired

Example: "2018-09-01"

candidates[].issue.release_datestring or nullrequired

Example: "2018-07-11"

candidates[].issue.foc_datestring or nullrequired

Example: "2018-06-18"

candidates[].issue.is_unreleasedbooleanrequired
candidates[].issue.cover_urlstring or nullrequired

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

candidates[].issue.imagesobject or nullrequired
candidates[].issue.images.thumbstring

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

candidates[].issue.images.cover_smstring

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

candidates[].issue.images.cover_mdstring

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

candidates[].issue.images.cover_lgstring

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

candidates[].issue.is_reprintbooleanrequired
candidates[].issue.content_rating_labelstring or nullrequired

Example: "Teen"

candidates[].issue.min_ageinteger or nullrequired

Example: 13

candidates[].issue.is_nsfwbooleanrequired
candidates[].issue.average_ratingnumber or nullrequired

Example: 4.5

candidates[].issue.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

candidates[].issue.seriesobject or null
candidates[].issue.series.idintegerrequired

Example: 123

candidates[].issue.series.namestring or nullrequired

Example: "The Amazing Spider-Man"

candidates[].issue.series.slugstring or nullrequired

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

candidates[].issue.series.start_yearinteger or nullrequired

Example: 2018

candidates[].issue.series.end_yearinteger or nullrequired

Example: 2022

candidates[].issue.series.volume_numberinteger or nullrequired

Example: 5

candidates[].issue.series.publication_typestring or nullrequired

Example: "regular_series"

candidates[].issue.series.formatstring or nullrequired

Example: "Standard"

candidates[].issue.series.cached_issues_countinteger or nullrequired

Example: 93

candidates[].issue.series.cover_urlstring or nullrequired

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

candidates[].issue.series.imagesobject or nullrequired
candidates[].issue.series.images.cover_smstring

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

candidates[].issue.series.images.cover_mdstring

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

candidates[].issue.series.images.cover_lgstring

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

candidates[].issue.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 lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

No photo, not an image, not one of the listed types, or over 5MB.

messagestringrequired

Example: "The file must be a valid image."

errorsobjectrequired
errors.imagearray of stringsrequired

Example: ["The file must be a valid image."]

Example body, from the documented examples

{
  "message": "The file must be a valid image.",
  "errors": {
    "image": [
      "The file must be a valid image."
    ]
  }
}
429

Rate limit exceeded. This endpoint allows 5 a minute and 100 a day (free) or 15 a minute and 500 a day (PRO), and 30 a minute across every caller. 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."
}
503

Cover matching is unavailable right now.

messagestringrequired

Example: "Cover matching is unavailable right now. Try again later or look the comic up by barcode."

Example body, from the documented examples

{
  "message": "Cover matching is unavailable right now. Try again later or look the comic up by barcode."
}

Example request

curl --request POST \
  'https://versedb.com/api/v1/lookup/cover' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --form 'image=@{PATH_TO_FILE}'

Example response 200

{
  "matched_by": "image",
  "clear_match": true,
  "issue_id": 5432,
  "variant_id": 789,
  "candidates": [
    {
      "issue_id": 5432,
      "variant_id": 789,
      "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,
          "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"
        }
      }
    }
  ]
}

Response headers

X-RateLimit-Limitinteger

Requests allowed in the current window.

X-RateLimit-Remaininginteger

Requests remaining in the current window.

Retry-Afterinteger

Seconds to wait before retrying.