Skip to content
VerseDB

Characters

Endpoints for browsing and searching comic book characters.

Characters include heroes, villains, and supporting characters across all publishers.

List characters.

GET/api/v1/characters
Requires a token

Returns paginated characters by name, with optional search and filters.

Query parameters

qstring

Search by character name. Without a search hit, matches the name or real name containing it.

Example: "spider-man"

publisher_idsstring

Comma-separated publisher IDs. Returns characters published by any of them.

Example: "1,2"

rolesstring

Comma-separated character roles (name or slug, such as hero or villain). Returns characters with any of them.

Example: "hero"

powersstring

Comma-separated power slugs. Returns characters with any of them.

Example: "flight"

sortstring

Pass any value to replace the relevance ordering applied to q results with the name.

Example: "name"

limitinteger

Results per page (max 50).

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

data[].namestring or nullrequired

Example: "Spider-Man (Peter Parker)"

data[].slugstring or nullrequired

Example: "spider-man-peter-parker"

data[].real_namestring or nullrequired

Example: "Peter Parker"

data[].aliasesarray of stringsrequired

Example: ["Spidey","Web-Head"]

data[].racestring or nullrequired

Example: "Human"

data[].image_urlstring or nullrequired

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

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

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

data[].images.profile_mdstring

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

data[].images.full_lgstring

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

data[].appearances_countintegerrequired

Example: 5400

data[].publisher_namestring or null

Present when the character has a publisher.

Example: "Marvel Comics"

data[].name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data[].aliases_i18nobjectrequired

Alternative names per language.

data[].original_localestring or nullrequired

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

Example: "en"

data[].real_name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

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

Example: 1

meta.frominteger or nullrequired

Example: 1

meta.last_pageintegerrequired

Example: 25

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

Example: 20

meta.tointeger or nullrequired

Example: 20

meta.totalintegerrequired

Example: 500

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

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

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

messagestringrequired

Example: "Too Many Attempts."

Example body, from the documented examples

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

Example request

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

Example response 200

{
  "data": [
    {
      "id": 456,
      "name": "Spider-Man (Peter Parker)",
      "slug": "spider-man-peter-parker",
      "real_name": "Peter Parker",
      "aliases": [
        "Spidey",
        "Web-Head"
      ],
      "race": "Human",
      "image_url": "https://...-full_lg.webp",
      "images": {
        "tile_sm": "https://...-tile_sm.webp",
        "profile_md": "https://...-profile_md.webp",
        "full_lg": "https://...-full_lg.webp"
      },
      "appearances_count": 5400,
      "publisher_name": "Marvel Comics",
      "name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      },
      "aliases_i18n": {
        "en": [
          "Kodansha Comics"
        ]
      },
      "original_locale": "en",
      "real_name_i18n": {
        "ja": {
          "value": "講談社",
          "reading": "こうだんしゃ",
          "source": "madb"
        }
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

Get character details.

GET/api/v1/characters/{character_id}
Requires a token

Returns a single character with full details including publishers and cached relationship counts (appearances, series, teams, story arcs) so clients can decide which related-entity tabs to expose.

Path parameters

character_idintegerrequired

The character ID.

Example: 456

Query parameters

languagesstring

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

Example: "ja,ko"

Responses

200

Success

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

dataobjectrequired
data.idintegerrequired

Example: 456

data.namestring or nullrequired

Example: "Spider-Man (Peter Parker)"

data.slugstring or nullrequired

Example: "spider-man-peter-parker"

data.real_namestring or nullrequired

Example: "Peter Parker"

data.aliasesarray of strings or nullrequired

Example: ["Spidey","Web-Head","Webslinger"]

data.image_urlstring or nullrequired

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

data.imagesobject or nullrequired
data.images.tile_smstring

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

data.images.profile_mdstring

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

data.images.full_lgstring

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

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

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

Example: ["Spidey"]

data.genderstring or nullrequired

Example: "male"

data.birthdaystring or nullrequired

Example: "2001-08-10"

data.racestring or nullrequired

Example: "Human"

data.birth_placestring or nullrequired

Example: "Queens, New York"

data.occupationstring or nullrequired

Example: "Photographer, Scientist"

data.heightstring or nullrequired

Example: "5'10\""

data.weightstring or nullrequired

Example: "167 lbs"

data.citizenshipstring or nullrequired

Example: "American"

data.educationstring or nullrequired

Example: "College"

data.appearances_countintegerrequired

Example: 12500

data.series_countintegerrequired

Example: 320

data.teams_countintegerrequired

Example: 8

data.story_arcs_countintegerrequired

Example: 47

data.eye_colorstring

Present when the character has one.

Example: "Hazel"

data.hair_colorstring

Present when the character has one.

Example: "Brown"

data.powersarray of strings

Present when the character has one.

Example: ["Super strength","Wall-crawling","Spider-sense"]

data.weaknessesarray of strings

Present when the character has one.

Example: ["Ethyl chloride"]

data.equipmentarray of strings

Present when the character has one.

Example: ["Web-shooters"]

data.abilitiesarray of strings

Present when the character has one.

Example: ["Genius-level intellect"]

data.rolesarray of strings

Present when the character has one.

Example: ["Hero"]

data.publisherobject
data.publisher.idintegerrequired

Example: 1

data.publisher.namestring or nullrequired

Example: "Marvel"

data.publisher.slugstring or nullrequired

Example: "marvel"

data.name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

data.aliases_i18nobjectrequired

Alternative names per language.

data.original_localestring or nullrequired

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

Example: "en"

data.real_name_i18nobjectrequired

One name per language, keyed by BCP 47 tag.

401

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

messagestringrequired

Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}
403

The token lacks the read:public ability.

messagestringrequired

Example: "Insufficient token scope."

Example body, from the documented examples

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

Not Found

messagestringrequired

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

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\Character] 456"
}
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/characters/456' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "id": 456,
    "name": "Spider-Man (Peter Parker)",
    "slug": "spider-man-peter-parker",
    "real_name": "Peter Parker",
    "aliases": [
      "Spidey",
      "Web-Head",
      "Webslinger"
    ],
    "image_url": "https://...-full_lg.webp",
    "images": {
      "tile_sm": "https://...-tile_sm.webp",
      "profile_md": "https://...-profile_md.webp",
      "full_lg": "https://...-full_lg.webp"
    },
    "alter_ego": [
      "Spidey"
    ],
    "gender": "male",
    "birthday": "2001-08-10",
    "race": "Human",
    "birth_place": "Queens, New York",
    "occupation": "Photographer, Scientist",
    "height": "5'10\"",
    "weight": "167 lbs",
    "citizenship": "American",
    "education": "College",
    "appearances_count": 12500,
    "series_count": 320,
    "teams_count": 8,
    "story_arcs_count": 47,
    "eye_color": "Hazel",
    "hair_color": "Brown",
    "powers": [
      "Super strength",
      "Wall-crawling",
      "Spider-sense"
    ],
    "weaknesses": [
      "Ethyl chloride"
    ],
    "equipment": [
      "Web-shooters"
    ],
    "abilities": [
      "Genius-level intellect"
    ],
    "roles": [
      "Hero"
    ],
    "publisher": {
      "id": 1,
      "name": "Marvel",
      "slug": "marvel"
    },
    "name_i18n": {
      "ja": {
        "value": "講談社",
        "reading": "こうだんしゃ",
        "source": "madb"
      }
    },
    "aliases_i18n": {
      "en": [
        "Kodansha Comics"
      ]
    },
    "original_locale": "en",
    "real_name_i18n": {
      "ja": {
        "value": "講談社",
        "reading": "こうだんしゃ",
        "source": "madb"
      }
    }
  }
}

Get character series.

GET/api/v1/characters/{character_id}/series
Requires a token

Returns paginated series where the character appears.

Path parameters

character_idintegerrequired

The character ID.

Example: 456

Query parameters

limitinteger

Results per page (max 50).

Example: 20

qstring

Optional case-insensitive search within these results.

Example: "batman"

mediumstring

Comma-separated series mediums to filter by (comic, manga, manhwa, manhua, bande_dessinee, magazine).

Example: "comic,manga"

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes, and Accept-Language is not read.

Example: "ja,ko"

Responses

200

Success

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

dataarray of objects
data[].idinteger

Example: 123

data[].namestring

Example: "Amazing Spider-Man"

data[].name_i18nobject
data[].aliases_i18nobject
data[].original_localestring

Example: "en"

data[].slugstring

Example: "amazing-spider-man-2018"

data[].start_yearinteger

Example: 2018

data[].end_yearinteger

Example: 2022

data[].image_urlstring

Example: "https://..."

metaobject
meta.current_pageinteger

Example: 1

meta.last_pageinteger

Example: 5

meta.per_pageinteger

Example: 20

meta.totalinteger

Example: 100

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

Example response 200

{
  "data": [
    {
      "id": 123,
      "name": "Amazing Spider-Man",
      "name_i18n": {},
      "aliases_i18n": {},
      "original_locale": "en",
      "slug": "amazing-spider-man-2018",
      "start_year": 2018,
      "end_year": 2022,
      "image_url": "https://..."
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100
  }
}

Get character issues.

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

Returns paginated issues where the character appears, ordered by release date.

Path parameters

character_idintegerrequired

The character ID.

Example: 456

Query parameters

limitinteger

Results per page (max 50).

Example: 20

qstring

Optional case-insensitive search within these results.

Example: "batman"

mediumstring

Comma-separated series mediums to filter by (comic, manga, manhwa, manhua, bande_dessinee, magazine).

Example: "comic,manga"

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes, and Accept-Language is not read.

Example: "ja,ko"

Responses

200

Success

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

dataarray of objects
data[].idinteger

Example: 5432

data[].numberstring

Example: "1"

data[].namestring

Example: "The Amazing Spider-Man #1"

data[].name_i18nobject
data[].release_datestring

Example: "2018-07-11"

data[].cover_urlstring

Example: "https://..."

data[].seriesobject
data[].series.idinteger

Example: 123

data[].series.namestring

Example: "Amazing Spider-Man"

metaobject
meta.current_pageinteger

Example: 1

meta.last_pageinteger

Example: 100

meta.per_pageinteger

Example: 20

meta.totalinteger

Example: 2000

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

Example response 200

{
  "data": [
    {
      "id": 5432,
      "number": "1",
      "name": "The Amazing Spider-Man #1",
      "name_i18n": {},
      "release_date": "2018-07-11",
      "cover_url": "https://...",
      "series": {
        "id": 123,
        "name": "Amazing Spider-Man"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 100,
    "per_page": 20,
    "total": 2000
  }
}

Get character teams.

GET/api/v1/characters/{character_id}/teams
Requires a token

Returns paginated teams the character is a member of, including membership details.

Path parameters

character_idintegerrequired

The character ID.

Example: 456

Query parameters

limitinteger

Results per page (max 50).

Example: 20

qstring

Optional case-insensitive search within these results.

Example: "batman"

languagesstring

Keep only these languages in the _i18n maps (comma-separated BCP 47 tags). No other field changes, and Accept-Language is not read.

Example: "ja,ko"

Responses

200

Success

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

dataarray of objects
data[].idinteger

Example: 10

data[].namestring

Example: "Avengers"

data[].name_i18nobject
data[].aliases_i18nobject
data[].original_localestring

Example: "en"

data[].slugstring

Example: "avengers"

data[].image_urlstring

Example: "https://..."

data[].membershipobject
data[].membership.rolestring

Example: "Member"

data[].membership.joined_datestring

Example: "2012-05-01"

data[].membership.left_datestring or null

Example: null

metaobject
meta.current_pageinteger

Example: 1

meta.last_pageinteger

Example: 1

meta.per_pageinteger

Example: 20

meta.totalinteger

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

Example response 200

{
  "data": [
    {
      "id": 10,
      "name": "Avengers",
      "name_i18n": {},
      "aliases_i18n": {},
      "original_locale": "en",
      "slug": "avengers",
      "image_url": "https://...",
      "membership": {
        "role": "Member",
        "joined_date": "2012-05-01",
        "left_date": null
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 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.