Skip to content
VerseDB

Discovery

Dynamic content discovery endpoints for the home screen and new releases.

These endpoints provide curated and time-sensitive content like upcoming releases, FOC (Final Order Cutoff) deadlines, and new first issues.

FOC deadlines.

GET/api/v1/discovery/foc
Requires a token

Returns issues with Final Order Cutoff (FOC) deadline within the next N days. FOC is when retailers must place final orders with distributors (typically 2 weeks before release).

Query parameters

limitinteger

Results per page (1-50).

Example: 10

pageinteger

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

Example: 1

daysinteger

FOC window in days (1-30).

Example: 7

start_datestring

Start of FOC window (YYYY-MM-DD). Defaults to today.

Example: "2026-03-15"

publisher_idsstring

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

Example: "1,4"

sortstring

foc_date (default: FOC date, then publisher, then series name), publisher (publisher, then FOC date, then series name) or series (series name, then FOC date).

Example: "foc_date"

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

data[].slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].series_idinteger or nullrequired

Example: 123

data[].issue_numberstring or nullrequired

Example: "1"

data[].namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].cover_datestring or nullrequired

Example: "2018-09-01"

data[].release_datestring or nullrequired

Example: "2018-07-11"

data[].foc_datestring or nullrequired

Example: "2018-06-18"

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

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

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

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

data[].images.cover_smstring

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

data[].images.cover_mdstring

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

data[].images.cover_lgstring

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

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

Example: "Teen"

data[].min_ageinteger or nullrequired

Example: 13

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

Example: 4.5

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

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

Example: 123

data[].series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].series.slugstring or nullrequired

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

data[].series.start_yearinteger or nullrequired

Example: 2018

data[].series.end_yearinteger or nullrequired

Example: 2022

data[].series.volume_numberinteger or nullrequired

Example: 5

data[].series.publication_typestring or nullrequired

Example: "regular_series"

data[].series.formatstring or nullrequired

Example: "Standard"

data[].series.cached_issues_countinteger or nullrequired

Example: 93

data[].series.cover_urlstring or nullrequired

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

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

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

data[].series.images.cover_mdstring

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

data[].series.images.cover_lgstring

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

data[].series.publisher_namestring or nullrequired

Example: "Marvel"

metaobjectrequired
meta.current_pageintegerrequired

Example: 1

meta.per_pageintegerrequired

Example: 10

meta.totalintegerrequired

Example: 28

meta.last_pageintegerrequired

Example: 3

meta.foc_window_daysintegerrequired

Example: 7

meta.foc_startstringrequired

Example: "2026-03-15"

meta.foc_endstringrequired

Example: "2026-03-22"

meta.sortstringrequired

Example: "foc_date"

meta.notestringrequired

Example: "FOC dates are estimates based on release_date - 14 days"

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

A query parameter out of range.

messagestringrequired

Example: "The days must not be greater than 30."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The days must not be greater than 30.",
  "errors": {
    "days": [
      "The days must not be greater than 30."
    ]
  }
}
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/discovery/foc' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 5432,
      "slug": "amazing-spider-man-1",
      "series_id": 123,
      "issue_number": "1",
      "name": "The Chameleon Strikes!",
      "cover_date": "2018-09-01",
      "release_date": "2018-07-11",
      "foc_date": "2018-06-18",
      "cover_url": "https://...-cover_lg.webp",
      "images": {
        "thumb": "https://...-thumb.webp",
        "cover_sm": "https://...-cover_sm.webp",
        "cover_md": "https://...-cover_md.webp",
        "cover_lg": "https://...-cover_lg.webp"
      },
      "content_rating_label": "Teen",
      "min_age": 13,
      "average_rating": 4.5,
      "name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      },
      "series": {
        "id": 123,
        "name": "The Amazing Spider-Man",
        "slug": "the-amazing-spider-man-2018",
        "start_year": 2018,
        "end_year": 2022,
        "volume_number": 5,
        "publication_type": "regular_series",
        "format": "Standard",
        "cached_issues_count": 93,
        "cover_url": "https://...-cover_lg.webp",
        "images": {
          "cover_sm": "https://...-cover_sm.webp",
          "cover_md": "https://...-cover_md.webp",
          "cover_lg": "https://...-cover_lg.webp"
        },
        "publisher_name": "Marvel"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 28,
    "last_page": 3,
    "foc_window_days": 7,
    "foc_start": "2026-03-15",
    "foc_end": "2026-03-22",
    "sort": "foc_date",
    "note": "FOC dates are estimates based on release_date - 14 days"
  }
}

Follow updates.

GET/api/v1/discovery/follow-updates
Requires a token

Returns recent releases from the titles, characters, creators, and teams the user follows. A Series is not followable — it reaches this feed through its Title, and every volume of that title counts.

follow_contexts and follow_types are top-level maps keyed by issue id: the context explains why the issue is shown ("New in X-Men"), the type is one of title, character, creator, team.

Query parameters

daysinteger

Lookback window in days (1-90).

Example: 30

pageinteger

Page number for pagination.

Example: 1

per_pageinteger

Items per page (1-50).

Example: 20

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

data[].slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].series_idinteger or nullrequired

Example: 123

data[].issue_numberstring or nullrequired

Example: "1"

data[].namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].cover_datestring or nullrequired

Example: "2018-09-01"

data[].release_datestring or nullrequired

Example: "2018-07-11"

data[].foc_datestring or nullrequired

Example: "2018-06-18"

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

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

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

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

data[].images.cover_smstring

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

data[].images.cover_mdstring

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

data[].images.cover_lgstring

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

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

Example: "Teen"

data[].min_ageinteger or nullrequired

Example: 13

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

Example: 4.5

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

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

Example: 123

data[].series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].series.slugstring or nullrequired

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

data[].series.start_yearinteger or nullrequired

Example: 2018

data[].series.end_yearinteger or nullrequired

Example: 2022

data[].series.volume_numberinteger or nullrequired

Example: 5

data[].series.publication_typestring or nullrequired

Example: "regular_series"

data[].series.formatstring or nullrequired

Example: "Standard"

data[].series.cached_issues_countinteger or nullrequired

Example: 93

data[].series.cover_urlstring or nullrequired

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

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

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

data[].series.images.cover_mdstring

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

data[].series.images.cover_lgstring

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

data[].series.publisher_namestring or nullrequired

Example: "Marvel"

follow_contextsobject or array
follow_typesobject or array
metaobjectrequired
meta.daysintegerrequired

Example: 30

meta.total_followsintegerrequired

Example: 12

meta.current_pageintegerrequired

Example: 1

meta.per_pageintegerrequired

Example: 20

meta.totalintegerrequired

Example: 1

meta.last_pageintegerrequired

Example: 1

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

A token without read:user.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

A query parameter out of range.

messagestringrequired

Example: "The days must not be greater than 30."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The days must not be greater than 30.",
  "errors": {
    "days": [
      "The days must not be greater than 30."
    ]
  }
}
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/discovery/follow-updates' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

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

Upcoming #1 issues.

GET/api/v1/discovery/upcoming-firsts
Requires a token

Returns upcoming first issues (#1) from new ongoing series within the next N days. Useful for discovering new series launches.

Query parameters

limitinteger

Results per page (1-50).

Example: 10

pageinteger

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

Example: 1

daysinteger

Lookahead window in days (1-90).

Example: 60

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

data[].slugstring or nullrequired

Example: "amazing-spider-man-1"

data[].series_idinteger or nullrequired

Example: 123

data[].issue_numberstring or nullrequired

Example: "1"

data[].namestring or nullrequired

Example: "The Chameleon Strikes!"

data[].cover_datestring or nullrequired

Example: "2018-09-01"

data[].release_datestring or nullrequired

Example: "2018-07-11"

data[].foc_datestring or nullrequired

Example: "2018-06-18"

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

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

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

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

data[].images.cover_smstring

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

data[].images.cover_mdstring

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

data[].images.cover_lgstring

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

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

Example: "Teen"

data[].min_ageinteger or nullrequired

Example: 13

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

Example: 4.5

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

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

Example: 123

data[].series.namestring or nullrequired

Example: "The Amazing Spider-Man"

data[].series.slugstring or nullrequired

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

data[].series.start_yearinteger or nullrequired

Example: 2018

data[].series.end_yearinteger or nullrequired

Example: 2022

data[].series.volume_numberinteger or nullrequired

Example: 5

data[].series.publication_typestring or nullrequired

Example: "regular_series"

data[].series.formatstring or nullrequired

Example: "Standard"

data[].series.cached_issues_countinteger or nullrequired

Example: 93

data[].series.cover_urlstring or nullrequired

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

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

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

data[].series.images.cover_mdstring

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

data[].series.images.cover_lgstring

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

data[].series.publisher_namestring or nullrequired

Example: "Marvel"

metaobjectrequired
meta.current_pageintegerrequired

Example: 1

meta.per_pageintegerrequired

Example: 10

meta.totalintegerrequired

Example: 28

meta.last_pageintegerrequired

Example: 3

meta.lookahead_daysintegerrequired

Example: 60

meta.window_startstringrequired

Example: "2026-03-15"

meta.window_endstringrequired

Example: "2026-05-14"

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

A query parameter out of range.

messagestringrequired

Example: "The days must not be greater than 30."

errorsobjectrequired

Example body, from the documented examples

{
  "message": "The days must not be greater than 30.",
  "errors": {
    "days": [
      "The days must not be greater than 30."
    ]
  }
}
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/discovery/upcoming-firsts' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

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

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.