Skip to content
VerseDB

Key Issue Reasons

Endpoints for browsing key issue reasons (e.g., "1st Appearance", "Death", "Origin"). These are reusable labels that can be attached to issues to indicate significance.

List key issue reasons.

GET/api/v1/key-issue-reasons
Requires a token

Returns active key issue reasons, optionally filtered by category or name. Reasons are written per issue rather than drawn from a fixed vocabulary, so there are far more of them than the category list suggests — pass q and limit for a picker rather than fetching the lot.

Query parameters

categorystring

Filter by category (appearance, story, creator, market, media).

Example: "appearance"

qstring

Match reasons whose name contains this.

Example: "1st appearance"

limitinteger

Cap the number returned (1-100). Applied only when q is present.

Example: 12

Responses

200

Success

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

dataarray of objectsrequired
data[].idintegerrequired

Example: 1

data[].namestring or nullrequired

Example: "1st Appearance"

data[].categorystring or nullrequired

appearance, story, creator, market or media.

Example: "appearance"

data[].descriptionstring or nullrequired

Example: "First appearance of a character."

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

Example response 200

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

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.