Lists

GET/api/v1/listsBrowse lists.
POST/api/v1/listsCreate list.
GET/api/v1/lists/systemBrowse system lists.
GET/api/v1/users/{user_id}/listsGet user's lists.
GET/api/v1/lists/{list_id}Get list.
PUT/api/v1/lists/{list_id}Update list.
DELETE/api/v1/lists/{list_id}Delete list.
POST/api/v1/lists/{list_id}/saveSave list.
DELETE/api/v1/lists/{list_id}/saveUnsave list.
POST/api/v1/lists/{list_id}/likeLike list, or react to it.
DELETE/api/v1/lists/{list_id}/likeUnlike list.
POST/api/v1/lists/{list_id}/convert-to-mixedOpen a list to any type.
POST/api/v1/lists/{list_id}/stop-ruleStop a list updating itself.
POST/api/v1/lists/{list_id}/mergeMerge a list into this one.
POST/api/v1/lists/{list_id}/itemsAdd item to list.
DELETE/api/v1/lists/{list_id}/items/{item_id}Remove item from list.
PUT/api/v1/lists/{list_id}/items/reorderReorder items.

Browse lists.

GET/api/v1/lists

Requires a token

Returns paginated public lists with filtering and sorting options. Only shows lists with at least one item.

Query parameters

qstring: Search by list title or description, tolerating small typos in the title.
Example: "spider-man"
entity_typestring: Filter by entity type (issues, series, characters, creators, story_arcs, teams). Matches lists declared as that type plus unrestricted lists holding at least one item of it.
Example: "issues"
typestring: Filter by who made it — curated for staff lists, community for everyone else. Omit for both.
Example: "curated"
sortstring: Sort order (featured, newest, popular, most_saved). Default: featured.
Example: "popular"
limitinteger: Items per page (max 100).
Example: 20
pageinteger: Page number; meta.last_page says where the list ends.
Example: 1

Responses

200

Success

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

dataarray of objectsrequired
data[].idintegerrequired: Example: 101
data[].titlestringrequired: Example: "Best Spider-Man Stories"
data[].slugstringrequired: Example: "best-spider-man-stories"
data[].descriptionstring: The first 150 characters; left out when the list has none.
Example: "My favorite Spidey moments"
data[].entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data[].list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data[].entity_type_labelstringrequired: Example: "Issues"
data[].is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data[].is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data[].is_rankedbooleanrequired: Example: true
data[].is_privatebooleanrequired: Example: false
data[].items_countintegerrequired: Example: 25
data[].saves_countintegerrequired: Example: 89
data[].likes_countintegerrequired: Example: 150
data[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data[].userobject or nullrequired: The owner; null once the account is gone.
data[].user.idintegerrequired: Example: 123
data[].user.usernamestring or nullrequired: Example: "comic_fan"
data[].user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data[].preview_itemsarray of objects: The list's first four items in its own order; left out when it holds none.
data[].preview_items[].idintegerrequired: Example: 1
data[].preview_items[].image_urlstring or nullrequired: Example: "https://...-cover_sm.webp"
data[].preview_items[].is_nsfwbooleanrequired: Example: false
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."
}

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

Example response 200

{
  "data": [
    {
      "id": 101,
      "title": "Best Spider-Man Stories",
      "slug": "best-spider-man-stories",
      "description": "My favorite Spidey moments",
      "entity_type": "issues",
      "list_type": "custom",
      "entity_type_label": "Issues",
      "is_curated": false,
      "is_smart": false,
      "is_ranked": true,
      "is_private": false,
      "items_count": 25,
      "saves_count": 89,
      "likes_count": 150,
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00",
      "user": {
        "id": 123,
        "username": "comic_fan",
        "avatar": "https://...-profile_md.webp"
      },
      "preview_items": [
        {
          "id": 1,
          "image_url": "https://...-cover_sm.webp",
          "is_nsfw": false
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

Create list.

POST/api/v1/lists

Requires a token

Creates a new user list. A list filled by hand holds items of any type, so entity_type is ignored without a smart-list rule.

Request body `application/json`

titlestringrequired: The name of the list (3 to 100 characters).
Example: "Best Batman Runs"
descriptionstring or null: An optional description (up to 2000 characters).
Example: "My favorite Batman story arcs ranked by quality."
entity_typestring or null: The kind of item a smart-list rules query matches; ignored without rules.
Example: "issues"
is_rankedboolean: Whether items in the list are ordered. Defaults to true.
Example: true
is_privateboolean: Whether the list is private. Requires a Pro subscription. Defaults to false.
Example: false
rulesobject or null: A smart-list rule, which builds the list from a query and keeps it current instead of filling it by hand. Requires a Pro subscription and entity_type (never mixed), and sets is_ranked to false, since the rule carries its own sort.

Responses

201

Created.

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

dataobjectrequired
data.idintegerrequired: Example: 101
data.titlestringrequired: Example: "Best Spider-Man Stories"
data.slugstringrequired: Example: "best-spider-man-stories"
data.descriptionstring or nullrequired: Example: "My favorite Spidey moments"
data.entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data.entity_type_labelstringrequired: Example: "Issues"
data.is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data.item_typesarray of stringsrequired: The types its items hold: its own type, or each type a mixed list holds.
Example: ["issues"]
data.is_rankedbooleanrequired: Example: true
data.sort_optionsobjectrequired: What sort takes on this list, each with its label; the empty key is its own order.
data.is_privatebooleanrequired: Example: false
data.statusstringrequired: published or draft.
Example: "published"
data.list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data.items_countintegerrequired: Example: 25
data.saves_countintegerrequired: Example: 89
data.likes_countintegerrequired: Example: 150
data.clones_countintegerrequired: Example: 3
data.created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data.is_rule_basedbooleanrequired: Example: false
data.last_refreshed_atstring or nullrequired: Example: "2024-01-16T04:00:00+00:00"
data.smart_pausedbooleanrequired: A rule-built list that stopped updating while its owner's Pro is inactive.
Example: false
data.cloned_from_list_idinteger or nullrequired: Example: null
data.cloned_fromobject: The list this one was cloned from, while it exists.
data.cloned_from.idintegerrequired: Example: 77
data.cloned_from.titlestring or nullrequired: Example: "Spider-Man Essentials"
data.cloned_from.slugstring or nullrequired: Example: "spider-man-essentials"
data.cloned_from.userobject or nullrequired
data.cloned_from.user.idintegerrequired: Example: 9
data.cloned_from.user.usernamestring or nullrequired: Example: "webhead"
data.userobject or nullrequired: The owner; null once the account is gone.
data.user.idintegerrequired: Example: 123
data.user.usernamestring or nullrequired: Example: "comic_fan"
data.user.namestring or nullrequired: Example: "comic_fan"
data.user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data.reactionsarray of objectsrequired: The reactions left on the list, the most used first.
data.reactions[].reactionstringrequired: Example: "heart"
data.reactions[].emojistringrequired: Example: "❤️"
data.reactions[].labelstringrequired: Example: "Love"
data.reactions[].countintegerrequired: Example: 12

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:list nor write:lists, or a free account already has its ten 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

The body failed validation.

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

curl --request POST \
  'https://versedb.com/api/v1/lists' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Best Batman Runs",
  "description": "My favorite Batman story arcs ranked by quality.",
  "entity_type": "issues",
  "is_ranked": true,
  "is_private": false,
  "rules": {
    "version": 2,
    "match": {
      "all": [
        {
          "field": "launch_date",
          "op": "within_last",
          "value": {
            "count": 3,
            "unit": "months"
          }
        }
      ]
    },
    "sort": {
      "field": "launch_date",
      "direction": "desc"
    },
    "limit": 500
  }
}'

Example response 201

{
  "data": {
    "id": 101,
    "title": "Best Spider-Man Stories",
    "slug": "best-spider-man-stories",
    "description": "My favorite Spidey moments",
    "entity_type": "issues",
    "entity_type_label": "Issues",
    "is_curated": false,
    "item_types": [
      "issues"
    ],
    "is_ranked": true,
    "sort_options": {
      "": "List order",
      "recent": "Recently added"
    },
    "is_private": false,
    "status": "published",
    "list_type": "custom",
    "items_count": 25,
    "saves_count": 89,
    "likes_count": 150,
    "clones_count": 3,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "is_smart": false,
    "is_rule_based": false,
    "last_refreshed_at": "2024-01-16T04:00:00+00:00",
    "smart_paused": false,
    "cloned_from_list_id": null,
    "cloned_from": {
      "id": 77,
      "title": "Spider-Man Essentials",
      "slug": "spider-man-essentials",
      "user": {
        "id": 9,
        "username": "webhead"
      }
    },
    "user": {
      "id": 123,
      "username": "comic_fan",
      "name": "comic_fan",
      "avatar": "https://...-profile_md.webp"
    },
    "reactions": [
      {
        "reaction": "heart",
        "emoji": "❤️",
        "label": "Love",
        "count": 12
      }
    ]
  }
}

Browse system lists.

GET/api/v1/lists/system

Requires a token

Returns platform-curated lists (no user owner). These are editorial picks and featured content.

Query parameters

entity_typestring: Filter by entity type (issues, series, characters, creators, story_arcs, teams).
Example: "issues"
sortstring: Sort order (newest, popular).
Example: "popular"
limitinteger: Items per page (max 100).
Example: 20
pageinteger: Page number; meta.last_page says where the list ends.
Example: 1

Responses

200

Success

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

dataarray of objectsrequired
data[].idintegerrequired: Example: 101
data[].titlestringrequired: Example: "Best Spider-Man Stories"
data[].slugstringrequired: Example: "best-spider-man-stories"
data[].descriptionstring: The first 150 characters; left out when the list has none.
Example: "My favorite Spidey moments"
data[].entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data[].list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data[].entity_type_labelstringrequired: Example: "Issues"
data[].is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data[].is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data[].is_rankedbooleanrequired: Example: true
data[].is_privatebooleanrequired: Example: false
data[].items_countintegerrequired: Example: 25
data[].saves_countintegerrequired: Example: 89
data[].likes_countintegerrequired: Example: 150
data[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data[].userobject or nullrequired: The owner; null once the account is gone.
data[].user.idintegerrequired: Example: 123
data[].user.usernamestring or nullrequired: Example: "comic_fan"
data[].user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data[].preview_itemsarray of objects: The list's first four items in its own order; left out when it holds none.
data[].preview_items[].idintegerrequired: Example: 1
data[].preview_items[].image_urlstring or nullrequired: Example: "https://...-cover_sm.webp"
data[].preview_items[].is_nsfwbooleanrequired: Example: false
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."
}

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

Example response 200

{
  "data": [
    {
      "id": 101,
      "title": "Best Spider-Man Stories",
      "slug": "best-spider-man-stories",
      "description": "My favorite Spidey moments",
      "entity_type": "issues",
      "list_type": "custom",
      "entity_type_label": "Issues",
      "is_curated": false,
      "is_smart": false,
      "is_ranked": true,
      "is_private": false,
      "items_count": 25,
      "saves_count": 89,
      "likes_count": 150,
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00",
      "user": {
        "id": 123,
        "username": "comic_fan",
        "avatar": "https://...-profile_md.webp"
      },
      "preview_items": [
        {
          "id": 1,
          "image_url": "https://...-cover_sm.webp",
          "is_nsfw": false
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

Get user's lists.

GET/api/v1/users/{user_id}/lists

Requires a token

Returns a user's public lists. Your own lists also include private and draft ones when the token has read:user.

Path parameters

user_idintegerrequired: The user ID.
Example: 123

Query parameters

entity_typestring: Filter by entity type (issues, series, etc.).
Example: "issues"
sortstring: Sort order (newest, popular, most_saved).
Example: "newest"
limitinteger: Items per page (max 100).
Example: 20
pageinteger: Page number; meta.last_page says where the list ends.
Example: 1

Responses

200

Success

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

dataarray of objectsrequired
data[].idintegerrequired: Example: 101
data[].titlestringrequired: Example: "Best Spider-Man Stories"
data[].slugstringrequired: Example: "best-spider-man-stories"
data[].descriptionstring: The first 150 characters; left out when the list has none.
Example: "My favorite Spidey moments"
data[].entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data[].list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data[].entity_type_labelstringrequired: Example: "Issues"
data[].is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data[].is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data[].is_rankedbooleanrequired: Example: true
data[].is_privatebooleanrequired: Example: false
data[].items_countintegerrequired: Example: 25
data[].saves_countintegerrequired: Example: 89
data[].likes_countintegerrequired: Example: 150
data[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data[].userobject or nullrequired: The owner; null once the account is gone.
data[].user.idintegerrequired: Example: 123
data[].user.usernamestring or nullrequired: Example: "comic_fan"
data[].user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data[].preview_itemsarray of objects: The list's first four items in its own order; left out when it holds none.
data[].preview_items[].idintegerrequired: Example: 1
data[].preview_items[].image_urlstring or nullrequired: Example: "https://...-cover_sm.webp"
data[].preview_items[].is_nsfwbooleanrequired: Example: false
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."
}

404

You blocked this user, or they blocked you.

messagestringrequired: Example: "Not Found"

Example body, from the documented examples

{
  "message": "Not Found"
}

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

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

Example response 200

{
  "data": [
    {
      "id": 101,
      "title": "Best Spider-Man Stories",
      "slug": "best-spider-man-stories",
      "description": "My favorite Spidey moments",
      "entity_type": "issues",
      "list_type": "custom",
      "entity_type_label": "Issues",
      "is_curated": false,
      "is_smart": false,
      "is_ranked": true,
      "is_private": false,
      "items_count": 25,
      "saves_count": 89,
      "likes_count": 150,
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00",
      "user": {
        "id": 123,
        "username": "comic_fan",
        "avatar": "https://...-profile_md.webp"
      },
      "preview_items": [
        {
          "id": 1,
          "image_url": "https://...-cover_sm.webp",
          "is_nsfw": false
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 25,
    "per_page": 20,
    "to": 20,
    "total": 500
  }
}

The token lacks the read:public ability; the list is private or a draft and the token may not read its owner's private data (read:user on the owner's own token); the list is for Pro members; or the request sent owned, read, reviewed, alert_filter, item_ids or alert_id, which only the app's own API reads.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No such list, or you blocked its owner, or they blocked you.

messagestringrequired: Example: "Not Found"

Example body, from the documented examples

{
  "message": "Not Found"
}

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

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

Example response 200

{
  "data": {
    "id": 101,
    "title": "Best Spider-Man Stories",
    "slug": "best-spider-man-stories",
    "description": "My favorite Spidey moments",
    "entity_type": "issues",
    "entity_type_label": "Issues",
    "is_curated": false,
    "item_types": [
      "issues"
    ],
    "is_ranked": true,
    "sort_options": {
      "": "List order",
      "recent": "Recently added"
    },
    "is_private": false,
    "status": "published",
    "list_type": "custom",
    "items_count": 25,
    "saves_count": 89,
    "likes_count": 150,
    "clones_count": 3,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "is_smart": false,
    "is_rule_based": false,
    "last_refreshed_at": "2024-01-16T04:00:00+00:00",
    "smart_paused": false,
    "cloned_from_list_id": null,
    "cloned_from": {
      "id": 77,
      "title": "Spider-Man Essentials",
      "slug": "spider-man-essentials",
      "user": {
        "id": 9,
        "username": "webhead"
      }
    },
    "user": {
      "id": 123,
      "username": "comic_fan",
      "name": "comic_fan",
      "avatar": "https://...-profile_md.webp"
    },
    "items": [
      {
        "id": 1,
        "position": 1,
        "note": "Classic!",
        "created_at": "2024-01-15T10:30:00+00:00",
        "updated_at": "2024-01-15T10:30:00+00:00",
        "variant_id": 7,
        "variant": {
          "id": 7,
          "name": "Virgin Variant",
          "ratio": "1:25",
          "cover_image_url": "https://...-cover_md.webp"
        },
        "entity_type": "issues",
        "entity": {
          "id": 5432,
          "slug": "the-amazing-spider-man-1",
          "name": "The 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 Comics",
          "series": {
            "id": 88,
            "name": "The Amazing Spider-Man",
            "slug": "the-amazing-spider-man",
            "start_year": 2018
          }
        }
      }
    ],
    "reactions": [
      {
        "reaction": "heart",
        "emoji": "❤️",
        "label": "Love",
        "count": 12
      }
    ]
  }
}

Update list.

PUT/api/v1/lists/{list_id}

Requires a token

Updates a list's metadata. Wishlists can only update privacy settings.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Request body `application/json`

titlestring

The name of the list (3 to 100 characters).

Example: "Updated Title"

descriptionstring or null

The description (up to 2000 characters).

Example: "Updated description"

is_rankedboolean

Whether items are ranked.

Example: false

is_privateboolean

Whether the list is private. Non-wishlist private lists require a Pro subscription.

Example: true

statusstring

The list status.

One of "published", "draft"

Example: "published"

rulesobject

Replaces the smart-list rule. Only a list built from a rule takes one, and the list is rebuilt from the new rule unless its updates are paused.

Responses

200

Updated.

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

dataobjectrequired
data.idintegerrequired: Example: 101
data.titlestringrequired: Example: "Best Spider-Man Stories"
data.slugstringrequired: Example: "best-spider-man-stories"
data.descriptionstring or nullrequired: Example: "My favorite Spidey moments"
data.entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data.entity_type_labelstringrequired: Example: "Issues"
data.is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data.item_typesarray of stringsrequired: The types its items hold: its own type, or each type a mixed list holds.
Example: ["issues"]
data.is_rankedbooleanrequired: Example: true
data.sort_optionsobjectrequired: What sort takes on this list, each with its label; the empty key is its own order.
data.is_privatebooleanrequired: Example: false
data.statusstringrequired: published or draft.
Example: "published"
data.list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data.items_countintegerrequired: Example: 25
data.saves_countintegerrequired: Example: 89
data.likes_countintegerrequired: Example: 150
data.clones_countintegerrequired: Example: 3
data.created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data.is_rule_basedbooleanrequired: Example: false
data.last_refreshed_atstring or nullrequired: Example: "2024-01-16T04:00:00+00:00"
data.smart_pausedbooleanrequired: A rule-built list that stopped updating while its owner's Pro is inactive.
Example: false
data.cloned_from_list_idinteger or nullrequired: Example: null
data.cloned_fromobject: The list this one was cloned from, while it exists.
data.cloned_from.idintegerrequired: Example: 77
data.cloned_from.titlestring or nullrequired: Example: "Spider-Man Essentials"
data.cloned_from.slugstring or nullrequired: Example: "spider-man-essentials"
data.cloned_from.userobject or nullrequired
data.cloned_from.user.idintegerrequired: Example: 9
data.cloned_from.user.usernamestring or nullrequired: Example: "webhead"
data.userobject or nullrequired: The owner; null once the account is gone.
data.user.idintegerrequired: Example: 123
data.user.usernamestring or nullrequired: Example: "comic_fan"
data.user.namestring or nullrequired: Example: "comic_fan"
data.user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data.itemsarray of objectsrequired: Every item, in the list's own order or by sort.
data.items[].idintegerrequired: Example: 1
data.items[].positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
data.items[].notestring or nullrequired: Example: "Classic!"
data.items[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].variant_idinteger or nullrequired: Example: 7
data.items[].variantobject: The pinned cover, while it exists.
data.items[].variant.idintegerrequired: Example: 7
data.items[].variant.namestring or nullrequired: Example: "Virgin Variant"
data.items[].variant.ratiostring or nullrequired: Example: "1:25"
data.items[].variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
data.items[].entityobject: Left out once the entity is gone.
data.items[].entity.idintegerrequired: Example: 5432
data.items[].entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
data.items[].entity.namestring or nullrequired: Example: "The Amazing Spider-Man #1"
data.items[].entity.issue_numberstring or nullrequired: Example: "1"
data.items[].entity.release_datestring or nullrequired: Example: "2018-07-11"
data.items[].entity.foc_datestring or nullrequired: Example: "2018-06-18"
data.items[].entity.image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity.is_nsfwboolean or nullrequired
data.items[].entity.publisherstring or nullrequired: Example: "Marvel Comics"
data.items[].entity.seriesobject or nullrequired
data.items[].entity.series.idintegerrequired: Example: 88
data.items[].entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
data.items[].entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
data.items[].entity.series.start_yearinteger or nullrequired: Example: 2018
data.reactionsarray of objectsrequired: The reactions left on the list, the most used first.
data.reactions[].reactionstringrequired: Example: "heart"
data.reactions[].emojistringrequired: Example: "❤️"
data.reactions[].labelstringrequired: Example: "Love"
data.reactions[].countintegerrequired: Example: 12

401

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

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The list is not yours to update, or the token holds neither write:list nor write:lists.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

422

The body failed validation.

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

curl --request PUT \
  'https://versedb.com/api/v1/lists/101' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Updated Title",
  "description": "Updated description",
  "is_ranked": false,
  "is_private": true,
  "status": "published",
  "rules": {
    "version": 2,
    "match": {
      "all": [
        {
          "field": "launch_date",
          "op": "within_last",
          "value": {
            "count": 3,
            "unit": "months"
          }
        }
      ]
    },
    "sort": {
      "field": "launch_date",
      "direction": "desc"
    },
    "limit": 500
  }
}'

Example response 200

{
  "data": {
    "id": 101,
    "title": "Best Spider-Man Stories",
    "slug": "best-spider-man-stories",
    "description": "My favorite Spidey moments",
    "entity_type": "issues",
    "entity_type_label": "Issues",
    "is_curated": false,
    "item_types": [
      "issues"
    ],
    "is_ranked": true,
    "sort_options": {
      "": "List order",
      "recent": "Recently added"
    },
    "is_private": false,
    "status": "published",
    "list_type": "custom",
    "items_count": 25,
    "saves_count": 89,
    "likes_count": 150,
    "clones_count": 3,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "is_smart": false,
    "is_rule_based": false,
    "last_refreshed_at": "2024-01-16T04:00:00+00:00",
    "smart_paused": false,
    "cloned_from_list_id": null,
    "cloned_from": {
      "id": 77,
      "title": "Spider-Man Essentials",
      "slug": "spider-man-essentials",
      "user": {
        "id": 9,
        "username": "webhead"
      }
    },
    "user": {
      "id": 123,
      "username": "comic_fan",
      "name": "comic_fan",
      "avatar": "https://...-profile_md.webp"
    },
    "items": [
      {
        "id": 1,
        "position": 1,
        "note": "Classic!",
        "created_at": "2024-01-15T10:30:00+00:00",
        "updated_at": "2024-01-15T10:30:00+00:00",
        "variant_id": 7,
        "variant": {
          "id": 7,
          "name": "Virgin Variant",
          "ratio": "1:25",
          "cover_image_url": "https://...-cover_md.webp"
        },
        "entity_type": "issues",
        "entity": {
          "id": 5432,
          "slug": "the-amazing-spider-man-1",
          "name": "The 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 Comics",
          "series": {
            "id": 88,
            "name": "The Amazing Spider-Man",
            "slug": "the-amazing-spider-man",
            "start_year": 2018
          }
        }
      }
    ],
    "reactions": [
      {
        "reaction": "heart",
        "emoji": "❤️",
        "label": "Love",
        "count": 12
      }
    ]
  }
}

Delete list.

DELETE/api/v1/lists/{list_id}

Requires a token

Permanently deletes a list and all its items. Wishlists cannot be deleted.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Responses

204

Deleted.

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:list nor write:lists, the list is not yours, or it is your wishlist.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

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

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

Save list.

POST/api/v1/lists/{list_id}/save

Requires a token

Saves a list to the user's saved lists for quick access. Cannot save your own lists.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Responses

200

Already Saved

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

messagestringrequired: Example: "List is already saved."
savedbooleanrequired: Example: true

201

Saved

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

messagestringrequired: Example: "List saved successfully."
savedbooleanrequired: Example: true
saves_countintegerrequired: Example: 90

Example body, from the documented examples

{
  "message": "List saved successfully.",
  "saved": true,
  "saves_count": 90
}

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:list nor write:lists, or the list is your own or private.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

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

curl --request POST \
  'https://versedb.com/api/v1/lists/101/save' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "message": "List is already saved.",
  "saved": true
}

Unsave list.

DELETE/api/v1/lists/{list_id}/save

Requires a token

Removes a list from the user's saved lists.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Responses

200

Success.

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

messagestringrequired: Example: "List unsaved successfully."
savedbooleanrequired: Example: false
saves_countintegerrequired: Example: 89

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:list nor write:lists.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

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

curl --request DELETE \
  'https://versedb.com/api/v1/lists/101/save' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "message": "List unsaved successfully.",
  "saved": false,
  "saves_count": 89
}

Like list, or react to it.

POST/api/v1/lists/{list_id}/like

Requires a token

With no body this likes the list. Send reaction to leave that reaction instead, or to change the one already held; DELETE takes it back whichever it is. A member holds one reaction per list and every reaction counts toward likes_count. Cannot like your own lists.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Request body `application/json`

reactionstring: One of heart, laugh, wow, fire, clap, confused. Omit for a plain like.
Example: "clap"

Responses

200

Success.

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

messagestringrequired: Example: "Reaction changed."
likedbooleanrequired: Example: true
likes_countintegerrequired: Example: 151
my_reactionstring or nullrequired: The reaction the user now holds, null for none.
Example: "fire"
reactionsarray of objectsrequired: Each reaction left on the list with its count, most used first.
reactions[].reactionstringrequired: Example: "heart"
reactions[].emojistringrequired: Example: "❤️"
reactions[].labelstringrequired: Example: "Love"
reactions[].countintegerrequired: Example: 150

201

Liked

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

messagestringrequired: Example: "List liked successfully."
likedbooleanrequired: Example: true
likes_countintegerrequired: Example: 151
my_reactionstring or nullrequired: The reaction the user now holds, null for none.
Example: "clap"
reactionsarray of objectsrequired: Each reaction left on the list with its count, most used first.
reactions[].reactionstringrequired: Example: "heart"
reactions[].emojistringrequired: Example: "❤️"
reactions[].labelstringrequired: Example: "Love"
reactions[].countintegerrequired: Example: 150

Example body, from the documented examples

{
  "message": "List liked successfully.",
  "liked": true,
  "likes_count": 151,
  "my_reaction": "clap",
  "reactions": [
    {
      "reaction": "heart",
      "emoji": "❤️",
      "label": "Love",
      "count": 150
    }
  ]
}

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:list nor write:lists, or the list is your own or private.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

422

Unknown reaction

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

messagestringrequired: Example: "That reaction is not available here."
errorsobjectrequired
errors.reactionarray of stringsrequired: Example: ["That reaction is not available here."]
available_reactionsarray of stringsrequired: Example: ["heart","laugh","wow","fire","clap","confused"]

Example body, from the documented examples

{
  "message": "That reaction is not available here.",
  "errors": {
    "reaction": [
      "That reaction is not available here."
    ]
  },
  "available_reactions": [
    "heart",
    "laugh",
    "wow",
    "fire",
    "clap",
    "confused"
  ]
}

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

curl --request POST \
  'https://versedb.com/api/v1/lists/101/like' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "reaction": "clap"
}'

Example response 200

{
  "message": "Reaction changed.",
  "liked": true,
  "likes_count": 151,
  "my_reaction": "fire",
  "reactions": [
    {
      "reaction": "heart",
      "emoji": "❤️",
      "label": "Love",
      "count": 150
    }
  ]
}

Unlike list.

DELETE/api/v1/lists/{list_id}/like

Requires a token

Removes the user's like or reaction from a list.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Responses

200

Success.

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

messagestringrequired: Example: "List unliked successfully."
likedbooleanrequired: Example: false
likes_countintegerrequired: Example: 151
my_reactionstring or nullrequired: The reaction the user now holds, null for none.
Example: null
reactionsarray of objectsrequired: Each reaction left on the list with its count, most used first.
reactions[].reactionstringrequired: Example: "heart"
reactions[].emojistringrequired: Example: "❤️"
reactions[].labelstringrequired: Example: "Love"
reactions[].countintegerrequired: Example: 150

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:list nor write:lists.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

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

curl --request DELETE \
  'https://versedb.com/api/v1/lists/101/like' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "message": "List unliked successfully.",
  "liked": false,
  "likes_count": 151,
  "my_reaction": null,
  "reactions": [
    {
      "reaction": "heart",
      "emoji": "❤️",
      "label": "Love",
      "count": 150
    }
  ]
}

Open a list to any type.

POST/api/v1/lists/{list_id}/convert-to-mixed

Requires a token

One-way: broadens a single-type list so it can hold items of any type. Existing items keep their own type. It cannot be narrowed back, and a wishlist already holds any type.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Responses

200

Converted.

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

dataobjectrequired
data.idintegerrequired: Example: 101
data.titlestringrequired: Example: "Best Spider-Man Stories"
data.slugstringrequired: Example: "best-spider-man-stories"
data.descriptionstring or nullrequired: Example: "My favorite Spidey moments"
data.entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data.entity_type_labelstringrequired: Example: "Issues"
data.is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data.item_typesarray of stringsrequired: The types its items hold: its own type, or each type a mixed list holds.
Example: ["issues"]
data.is_rankedbooleanrequired: Example: true
data.sort_optionsobjectrequired: What sort takes on this list, each with its label; the empty key is its own order.
data.is_privatebooleanrequired: Example: false
data.statusstringrequired: published or draft.
Example: "published"
data.list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data.items_countintegerrequired: Example: 25
data.saves_countintegerrequired: Example: 89
data.likes_countintegerrequired: Example: 150
data.clones_countintegerrequired: Example: 3
data.created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data.is_rule_basedbooleanrequired: Example: false
data.last_refreshed_atstring or nullrequired: Example: "2024-01-16T04:00:00+00:00"
data.smart_pausedbooleanrequired: A rule-built list that stopped updating while its owner's Pro is inactive.
Example: false
data.cloned_from_list_idinteger or nullrequired: Example: null
data.cloned_fromobject: The list this one was cloned from, while it exists.
data.cloned_from.idintegerrequired: Example: 77
data.cloned_from.titlestring or nullrequired: Example: "Spider-Man Essentials"
data.cloned_from.slugstring or nullrequired: Example: "spider-man-essentials"
data.cloned_from.userobject or nullrequired
data.cloned_from.user.idintegerrequired: Example: 9
data.cloned_from.user.usernamestring or nullrequired: Example: "webhead"
data.userobject or nullrequired: The owner; null once the account is gone.
data.user.idintegerrequired: Example: 123
data.user.usernamestring or nullrequired: Example: "comic_fan"
data.user.namestring or nullrequired: Example: "comic_fan"
data.user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data.itemsarray of objectsrequired: Every item, in the list's own order or by sort.
data.items[].idintegerrequired: Example: 1
data.items[].positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
data.items[].notestring or nullrequired: Example: "Classic!"
data.items[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].variant_idinteger or nullrequired: Example: 7
data.items[].variantobject: The pinned cover, while it exists.
data.items[].variant.idintegerrequired: Example: 7
data.items[].variant.namestring or nullrequired: Example: "Virgin Variant"
data.items[].variant.ratiostring or nullrequired: Example: "1:25"
data.items[].variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
data.items[].entityobject: Left out once the entity is gone.
data.items[].entity.idintegerrequired: Example: 5432
data.items[].entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
data.items[].entity.namestring or nullrequired: Example: "The Amazing Spider-Man #1"
data.items[].entity.issue_numberstring or nullrequired: Example: "1"
data.items[].entity.release_datestring or nullrequired: Example: "2018-07-11"
data.items[].entity.foc_datestring or nullrequired: Example: "2018-06-18"
data.items[].entity.image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity.is_nsfwboolean or nullrequired
data.items[].entity.publisherstring or nullrequired: Example: "Marvel Comics"
data.items[].entity.seriesobject or nullrequired
data.items[].entity.series.idintegerrequired: Example: 88
data.items[].entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
data.items[].entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
data.items[].entity.series.start_yearinteger or nullrequired: Example: 2018
data.reactionsarray of objectsrequired: The reactions left on the list, the most used first.
data.reactions[].reactionstringrequired: Example: "heart"
data.reactions[].emojistringrequired: Example: "❤️"
data.reactions[].labelstringrequired: Example: "Love"
data.reactions[].countintegerrequired: Example: 12

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:list nor write:lists, or the list is not yours.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

422

Not convertible.

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

messagestringrequired: Example: "This list already holds any type."

Example body, from the documented examples

{
  "message": "This list already holds any type."
}

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

curl --request POST \
  'https://versedb.com/api/v1/lists/101/convert-to-mixed' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "id": 101,
    "title": "Best Spider-Man Stories",
    "slug": "best-spider-man-stories",
    "description": "My favorite Spidey moments",
    "entity_type": "issues",
    "entity_type_label": "Issues",
    "is_curated": false,
    "item_types": [
      "issues"
    ],
    "is_ranked": true,
    "sort_options": {
      "": "List order",
      "recent": "Recently added"
    },
    "is_private": false,
    "status": "published",
    "list_type": "custom",
    "items_count": 25,
    "saves_count": 89,
    "likes_count": 150,
    "clones_count": 3,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "is_smart": false,
    "is_rule_based": false,
    "last_refreshed_at": "2024-01-16T04:00:00+00:00",
    "smart_paused": false,
    "cloned_from_list_id": null,
    "cloned_from": {
      "id": 77,
      "title": "Spider-Man Essentials",
      "slug": "spider-man-essentials",
      "user": {
        "id": 9,
        "username": "webhead"
      }
    },
    "user": {
      "id": 123,
      "username": "comic_fan",
      "name": "comic_fan",
      "avatar": "https://...-profile_md.webp"
    },
    "items": [
      {
        "id": 1,
        "position": 1,
        "note": "Classic!",
        "created_at": "2024-01-15T10:30:00+00:00",
        "updated_at": "2024-01-15T10:30:00+00:00",
        "variant_id": 7,
        "variant": {
          "id": 7,
          "name": "Virgin Variant",
          "ratio": "1:25",
          "cover_image_url": "https://...-cover_md.webp"
        },
        "entity_type": "issues",
        "entity": {
          "id": 5432,
          "slug": "the-amazing-spider-man-1",
          "name": "The 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 Comics",
          "series": {
            "id": 88,
            "name": "The Amazing Spider-Man",
            "slug": "the-amazing-spider-man",
            "start_year": 2018
          }
        }
      }
    ],
    "reactions": [
      {
        "reaction": "heart",
        "emoji": "❤️",
        "label": "Love",
        "count": 12
      }
    ]
  }
}

Stop a list updating itself.

POST/api/v1/lists/{list_id}/stop-rule

Requires a token

One-way: drops a smart list's rule and keeps every item the last refresh left, handing the contents back for editing by hand. A rule is only ever attached when a list is created, so it cannot be put back.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Responses

200

Success.

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

dataobjectrequired
data.idintegerrequired: Example: 101
data.titlestringrequired: Example: "Best Spider-Man Stories"
data.slugstringrequired: Example: "best-spider-man-stories"
data.descriptionstring or nullrequired: Example: "My favorite Spidey moments"
data.entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data.entity_type_labelstringrequired: Example: "Issues"
data.is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data.item_typesarray of stringsrequired: The types its items hold: its own type, or each type a mixed list holds.
Example: ["issues"]
data.is_rankedbooleanrequired: Example: true
data.sort_optionsobjectrequired: What sort takes on this list, each with its label; the empty key is its own order.
data.is_privatebooleanrequired: Example: false
data.statusstringrequired: published or draft.
Example: "published"
data.list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data.items_countintegerrequired: Example: 25
data.saves_countintegerrequired: Example: 89
data.likes_countintegerrequired: Example: 150
data.clones_countintegerrequired: Example: 3
data.created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data.is_rule_basedbooleanrequired: Example: false
data.last_refreshed_atstring or nullrequired: Example: "2024-01-16T04:00:00+00:00"
data.smart_pausedbooleanrequired: A rule-built list that stopped updating while its owner's Pro is inactive.
Example: false
data.cloned_from_list_idinteger or nullrequired: Example: null
data.cloned_fromobject: The list this one was cloned from, while it exists.
data.cloned_from.idintegerrequired: Example: 77
data.cloned_from.titlestring or nullrequired: Example: "Spider-Man Essentials"
data.cloned_from.slugstring or nullrequired: Example: "spider-man-essentials"
data.cloned_from.userobject or nullrequired
data.cloned_from.user.idintegerrequired: Example: 9
data.cloned_from.user.usernamestring or nullrequired: Example: "webhead"
data.userobject or nullrequired: The owner; null once the account is gone.
data.user.idintegerrequired: Example: 123
data.user.usernamestring or nullrequired: Example: "comic_fan"
data.user.namestring or nullrequired: Example: "comic_fan"
data.user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data.itemsarray of objectsrequired: Every item, in the list's own order or by sort.
data.items[].idintegerrequired: Example: 1
data.items[].positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
data.items[].notestring or nullrequired: Example: "Classic!"
data.items[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].variant_idinteger or nullrequired: Example: 7
data.items[].variantobject: The pinned cover, while it exists.
data.items[].variant.idintegerrequired: Example: 7
data.items[].variant.namestring or nullrequired: Example: "Virgin Variant"
data.items[].variant.ratiostring or nullrequired: Example: "1:25"
data.items[].variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
data.items[].entityobject: Left out once the entity is gone.
data.items[].entity.idintegerrequired: Example: 5432
data.items[].entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
data.items[].entity.namestring or nullrequired: Example: "The Amazing Spider-Man #1"
data.items[].entity.issue_numberstring or nullrequired: Example: "1"
data.items[].entity.release_datestring or nullrequired: Example: "2018-07-11"
data.items[].entity.foc_datestring or nullrequired: Example: "2018-06-18"
data.items[].entity.image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity.is_nsfwboolean or nullrequired
data.items[].entity.publisherstring or nullrequired: Example: "Marvel Comics"
data.items[].entity.seriesobject or nullrequired
data.items[].entity.series.idintegerrequired: Example: 88
data.items[].entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
data.items[].entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
data.items[].entity.series.start_yearinteger or nullrequired: Example: 2018
data.reactionsarray of objectsrequired: The reactions left on the list, the most used first.
data.reactions[].reactionstringrequired: Example: "heart"
data.reactions[].emojistringrequired: Example: "❤️"
data.reactions[].labelstringrequired: Example: "Love"
data.reactions[].countintegerrequired: Example: 12

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:list nor write:lists, or the list is not yours.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

422

Not rule-built.

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

messagestringrequired: Example: "This list is not built from a rule."

Example body, from the documented examples

{
  "message": "This list is not built from a rule."
}

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

curl --request POST \
  'https://versedb.com/api/v1/lists/101/stop-rule' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "id": 101,
    "title": "Best Spider-Man Stories",
    "slug": "best-spider-man-stories",
    "description": "My favorite Spidey moments",
    "entity_type": "issues",
    "entity_type_label": "Issues",
    "is_curated": false,
    "item_types": [
      "issues"
    ],
    "is_ranked": true,
    "sort_options": {
      "": "List order",
      "recent": "Recently added"
    },
    "is_private": false,
    "status": "published",
    "list_type": "custom",
    "items_count": 25,
    "saves_count": 89,
    "likes_count": 150,
    "clones_count": 3,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "is_smart": false,
    "is_rule_based": false,
    "last_refreshed_at": "2024-01-16T04:00:00+00:00",
    "smart_paused": false,
    "cloned_from_list_id": null,
    "cloned_from": {
      "id": 77,
      "title": "Spider-Man Essentials",
      "slug": "spider-man-essentials",
      "user": {
        "id": 9,
        "username": "webhead"
      }
    },
    "user": {
      "id": 123,
      "username": "comic_fan",
      "name": "comic_fan",
      "avatar": "https://...-profile_md.webp"
    },
    "items": [
      {
        "id": 1,
        "position": 1,
        "note": "Classic!",
        "created_at": "2024-01-15T10:30:00+00:00",
        "updated_at": "2024-01-15T10:30:00+00:00",
        "variant_id": 7,
        "variant": {
          "id": 7,
          "name": "Virgin Variant",
          "ratio": "1:25",
          "cover_image_url": "https://...-cover_md.webp"
        },
        "entity_type": "issues",
        "entity": {
          "id": 5432,
          "slug": "the-amazing-spider-man-1",
          "name": "The 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 Comics",
          "series": {
            "id": 88,
            "name": "The Amazing Spider-Man",
            "slug": "the-amazing-spider-man",
            "start_year": 2018
          }
        }
      }
    ],
    "reactions": [
      {
        "reaction": "heart",
        "emoji": "❤️",
        "label": "Love",
        "count": 12
      }
    ]
  }
}

Merge a list into this one.

POST/api/v1/lists/{list_id}/merge

Requires a token

Pulls every item from the source list into this (destination) list, skipping items already present (by entity + variant) and appending the rest. Both lists must be owned by the authenticated user. Merging items of a different type opens this list to any type.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Request body `application/json`

source_list_idintegerrequired: The list whose items are pulled into this list. Must be owned by the authenticated user.
Example: 207
delete_sourceboolean: Whether to delete the source list after its items are merged in. Defaults to false.
Example: false

Responses

200

Merged.

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

dataobjectrequired
data.idintegerrequired: Example: 101
data.titlestringrequired: Example: "Best Spider-Man Stories"
data.slugstringrequired: Example: "best-spider-man-stories"
data.descriptionstring or nullrequired: Example: "My favorite Spidey moments"
data.entity_typestringrequired: issues, series, characters, creators, story_arcs, teams, or mixed for a list of any type.
Example: "issues"
data.entity_type_labelstringrequired: Example: "Issues"
data.is_curatedbooleanrequired: The list is VerseDB's own.
Example: false
data.item_typesarray of stringsrequired: The types its items hold: its own type, or each type a mixed list holds.
Example: ["issues"]
data.is_rankedbooleanrequired: Example: true
data.sort_optionsobjectrequired: What sort takes on this list, each with its label; the empty key is its own order.
data.is_privatebooleanrequired: Example: false
data.statusstringrequired: published or draft.
Example: "published"
data.list_typestringrequired: custom, wishlist or reading_guide.
Example: "custom"
data.items_countintegerrequired: Example: 25
data.saves_countintegerrequired: Example: 89
data.likes_countintegerrequired: Example: 150
data.clones_countintegerrequired: Example: 3
data.created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.is_smartbooleanrequired: A rule keeps the list up to date.
Example: false
data.is_rule_basedbooleanrequired: Example: false
data.last_refreshed_atstring or nullrequired: Example: "2024-01-16T04:00:00+00:00"
data.smart_pausedbooleanrequired: A rule-built list that stopped updating while its owner's Pro is inactive.
Example: false
data.cloned_from_list_idinteger or nullrequired: Example: null
data.cloned_fromobject: The list this one was cloned from, while it exists.
data.cloned_from.idintegerrequired: Example: 77
data.cloned_from.titlestring or nullrequired: Example: "Spider-Man Essentials"
data.cloned_from.slugstring or nullrequired: Example: "spider-man-essentials"
data.cloned_from.userobject or nullrequired
data.cloned_from.user.idintegerrequired: Example: 9
data.cloned_from.user.usernamestring or nullrequired: Example: "webhead"
data.userobject or nullrequired: The owner; null once the account is gone.
data.user.idintegerrequired: Example: 123
data.user.usernamestring or nullrequired: Example: "comic_fan"
data.user.namestring or nullrequired: Example: "comic_fan"
data.user.avatarstring or nullrequired: Example: "https://...-profile_md.webp"
data.itemsarray of objectsrequired: Every item, in the list's own order or by sort.
data.items[].idintegerrequired: Example: 1
data.items[].positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
data.items[].notestring or nullrequired: Example: "Classic!"
data.items[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
data.items[].variant_idinteger or nullrequired: Example: 7
data.items[].variantobject: The pinned cover, while it exists.
data.items[].variant.idintegerrequired: Example: 7
data.items[].variant.namestring or nullrequired: Example: "Virgin Variant"
data.items[].variant.ratiostring or nullrequired: Example: "1:25"
data.items[].variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
data.items[].entityobject: Left out once the entity is gone.
data.items[].entity.idintegerrequired: Example: 5432
data.items[].entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
data.items[].entity.namestring or nullrequired: Example: "The Amazing Spider-Man #1"
data.items[].entity.issue_numberstring or nullrequired: Example: "1"
data.items[].entity.release_datestring or nullrequired: Example: "2018-07-11"
data.items[].entity.foc_datestring or nullrequired: Example: "2018-06-18"
data.items[].entity.image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.items[].entity.is_nsfwboolean or nullrequired
data.items[].entity.publisherstring or nullrequired: Example: "Marvel Comics"
data.items[].entity.seriesobject or nullrequired
data.items[].entity.series.idintegerrequired: Example: 88
data.items[].entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
data.items[].entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
data.items[].entity.series.start_yearinteger or nullrequired: Example: 2018
data.reactionsarray of objectsrequired: The reactions left on the list, the most used first.
data.reactions[].reactionstringrequired: Example: "heart"
data.reactions[].emojistringrequired: Example: "❤️"
data.reactions[].labelstringrequired: Example: "Love"
data.reactions[].countintegerrequired: Example: 12
mergeobjectrequired
merge.movedintegerrequired: Example: 4
merge.skipped_duplicatesintegerrequired: Example: 1
merge.converted_to_mixedbooleanrequired: Example: false
merge.source_deletedbooleanrequired: 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:list nor write:lists, or either list is not yours to merge.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID (Source list not found. when it is the source that is gone).

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

422

The body failed validation, or the merge is refused (an empty source, the item cap).

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

messagestringrequired: Example: "The source list has no items to merge."

Example body, from the documented examples

{
  "message": "The source list has no items to merge."
}

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

curl --request POST \
  'https://versedb.com/api/v1/lists/101/merge' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_list_id": 207,
  "delete_source": false
}'

Example response 200

{
  "data": {
    "id": 101,
    "title": "Best Spider-Man Stories",
    "slug": "best-spider-man-stories",
    "description": "My favorite Spidey moments",
    "entity_type": "issues",
    "entity_type_label": "Issues",
    "is_curated": false,
    "item_types": [
      "issues"
    ],
    "is_ranked": true,
    "sort_options": {
      "": "List order",
      "recent": "Recently added"
    },
    "is_private": false,
    "status": "published",
    "list_type": "custom",
    "items_count": 25,
    "saves_count": 89,
    "likes_count": 150,
    "clones_count": 3,
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "is_smart": false,
    "is_rule_based": false,
    "last_refreshed_at": "2024-01-16T04:00:00+00:00",
    "smart_paused": false,
    "cloned_from_list_id": null,
    "cloned_from": {
      "id": 77,
      "title": "Spider-Man Essentials",
      "slug": "spider-man-essentials",
      "user": {
        "id": 9,
        "username": "webhead"
      }
    },
    "user": {
      "id": 123,
      "username": "comic_fan",
      "name": "comic_fan",
      "avatar": "https://...-profile_md.webp"
    },
    "items": [
      {
        "id": 1,
        "position": 1,
        "note": "Classic!",
        "created_at": "2024-01-15T10:30:00+00:00",
        "updated_at": "2024-01-15T10:30:00+00:00",
        "variant_id": 7,
        "variant": {
          "id": 7,
          "name": "Virgin Variant",
          "ratio": "1:25",
          "cover_image_url": "https://...-cover_md.webp"
        },
        "entity_type": "issues",
        "entity": {
          "id": 5432,
          "slug": "the-amazing-spider-man-1",
          "name": "The 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 Comics",
          "series": {
            "id": 88,
            "name": "The Amazing Spider-Man",
            "slug": "the-amazing-spider-man",
            "start_year": 2018
          }
        }
      }
    ],
    "reactions": [
      {
        "reaction": "heart",
        "emoji": "❤️",
        "label": "Love",
        "count": 12
      }
    ]
  },
  "merge": {
    "moved": 4,
    "skipped_duplicates": 1,
    "converted_to_mixed": false,
    "source_deleted": false
  }
}

Add item to list.

POST/api/v1/lists/{list_id}/items

Requires a token

Adds an entity to a list. Free users: 100 items/list, PRO users: 500 items/list.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Request body `application/json`

entity_idintegerrequired: The ID of the entity to add. Must match the list's entity type (e.g., an issue ID for an issues list), or the type given in entity_type when the list holds any type.
Example: 42
entity_typestring or null: Required when the list holds any type: the type of the entity being added (issues, series, characters, creators, story_arcs, teams). Ignored on a single-type list.
Example: "issues"
variant_idinteger or null: Optional cover variant of the issue being added (issue items only). Must belong to entity_id. Omit for "any cover". The same issue can appear once per distinct variant.
Example: 7
positioninteger or null: Optional position in the list (1-based). Items are appended to the end if omitted.
Example: 1
notestring or null: An optional note for this list item (up to 500 characters).
Example: "The issue that started it all."

Responses

201

Added.

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

dataobjectrequired
data.idintegerrequired: Example: 1
data.positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
data.notestring or nullrequired: Example: "Classic!"
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: 7
data.variantobject: The pinned cover, while it exists.
data.variant.idintegerrequired: Example: 7
data.variant.namestring or nullrequired: Example: "Virgin Variant"
data.variant.ratiostring or nullrequired: Example: "1:25"
data.variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
data.entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
data.entityobject: Left out once the entity is gone.
data.entity.idintegerrequired: Example: 5432
data.entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
data.entity.namestring or nullrequired: Example: "The 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 Comics"
data.entity.seriesobject or nullrequired
data.entity.series.idintegerrequired: Example: 88
data.entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
data.entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
data.entity.series.start_yearinteger or nullrequired: Example: 2018

401

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

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The list is not yours to change or is built by a rule, the token holds neither write:list nor write:lists, or the list is at its item limit.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

409

The entity (with the same cover) is already in the list.

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

messagestringrequired: Example: "This item is already in the list."
itemobjectrequired
item.idintegerrequired: Example: 1
item.positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
item.notestring or nullrequired: Example: "Classic!"
item.created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
item.updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
item.variant_idinteger or nullrequired: Example: 7
item.variantobject: The pinned cover, while it exists.
item.variant.idintegerrequired: Example: 7
item.variant.namestring or nullrequired: Example: "Virgin Variant"
item.variant.ratiostring or nullrequired: Example: "1:25"
item.variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
item.entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
item.entityobject: Left out once the entity is gone.
item.entity.idintegerrequired: Example: 5432
item.entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
item.entity.namestring or nullrequired: Example: "The Amazing Spider-Man #1"
item.entity.issue_numberstring or nullrequired: Example: "1"
item.entity.release_datestring or nullrequired: Example: "2018-07-11"
item.entity.foc_datestring or nullrequired: Example: "2018-06-18"
item.entity.image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
item.entity.is_nsfwboolean or nullrequired
item.entity.publisherstring or nullrequired: Example: "Marvel Comics"
item.entity.seriesobject or nullrequired
item.entity.series.idintegerrequired: Example: 88
item.entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
item.entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
item.entity.series.start_yearinteger or nullrequired: Example: 2018

Example body, from the documented examples

{
  "message": "This item is already in the list.",
  "item": {
    "id": 1,
    "position": 1,
    "note": "Classic!",
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "variant_id": 7,
    "variant": {
      "id": 7,
      "name": "Virgin Variant",
      "ratio": "1:25",
      "cover_image_url": "https://...-cover_md.webp"
    },
    "entity_type": "issues",
    "entity": {
      "id": 5432,
      "slug": "the-amazing-spider-man-1",
      "name": "The 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 Comics",
      "series": {
        "id": 88,
        "name": "The Amazing Spider-Man",
        "slug": "the-amazing-spider-man",
        "start_year": 2018
      }
    }
  }
}

422

The body failed validation.

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

curl --request POST \
  'https://versedb.com/api/v1/lists/101/items' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "entity_id": 42,
  "entity_type": "issues",
  "variant_id": 7,
  "position": 1,
  "note": "The issue that started it all."
}'

Example response 201

{
  "data": {
    "id": 1,
    "position": 1,
    "note": "Classic!",
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00",
    "variant_id": 7,
    "variant": {
      "id": 7,
      "name": "Virgin Variant",
      "ratio": "1:25",
      "cover_image_url": "https://...-cover_md.webp"
    },
    "entity_type": "issues",
    "entity": {
      "id": 5432,
      "slug": "the-amazing-spider-man-1",
      "name": "The 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 Comics",
      "series": {
        "id": 88,
        "name": "The Amazing Spider-Man",
        "slug": "the-amazing-spider-man",
        "start_year": 2018
      }
    }
  }
}

Remove item from list.

DELETE/api/v1/lists/{list_id}/items/{item_id}

Requires a token

Removes an item from a list. Other items' positions are kept.

Path parameters

list_idintegerrequired: The list ID.
Example: 101
item_idintegerrequired: The list item ID.
Example: 501

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:list nor write:lists, or the list is not yours to change.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list or no list item has this ID, or the item belongs to another list (Item does not belong to this list.).

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

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

curl --request DELETE \
  'https://versedb.com/api/v1/lists/101/items/501' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Reorder items.

PUT/api/v1/lists/{list_id}/items/reorder

Requires a token

Reorders items in a ranked list by providing the new order of item IDs.

Path parameters

list_idintegerrequired: The list ID.
Example: 101

Request body `application/json`

item_idsarray of integersrequired: An ordered array of list item IDs representing the new order. All IDs must belong to this list with no duplicates.
Example: [3,1,2]

Responses

200

Reordered.

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

messagestringrequired: Example: "Items reordered successfully."
itemsarray of objectsrequired
items[].idintegerrequired: Example: 1
items[].positioninteger or nullrequired: Its place on a ranked or rule-built list.
Example: 1
items[].notestring or nullrequired: Example: "Classic!"
items[].created_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
items[].updated_atstringrequired: Example: "2024-01-15T10:30:00+00:00"
items[].variant_idinteger or nullrequired: Example: 7
items[].variantobject: The pinned cover, while it exists.
items[].variant.idintegerrequired: Example: 7
items[].variant.namestring or nullrequired: Example: "Virgin Variant"
items[].variant.ratiostring or nullrequired: Example: "1:25"
items[].variant.cover_image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
items[].entity_typestringrequired: issues, series, characters, creators, story_arcs or teams.
Example: "issues"
items[].entityobject: Left out once the entity is gone.
items[].entity.idintegerrequired: Example: 5432
items[].entity.slugstring or nullrequired: Example: "the-amazing-spider-man-1"
items[].entity.namestring or nullrequired: Example: "The Amazing Spider-Man #1"
items[].entity.issue_numberstring or nullrequired: Example: "1"
items[].entity.release_datestring or nullrequired: Example: "2018-07-11"
items[].entity.foc_datestring or nullrequired: Example: "2018-06-18"
items[].entity.image_urlstring or nullrequired: Example: "https://...-cover_md.webp"
items[].entity.is_nsfwboolean or nullrequired
items[].entity.publisherstring or nullrequired: Example: "Marvel Comics"
items[].entity.seriesobject or nullrequired
items[].entity.series.idintegerrequired: Example: 88
items[].entity.series.namestring or nullrequired: Example: "The Amazing Spider-Man"
items[].entity.series.slugstring or nullrequired: Example: "the-amazing-spider-man"
items[].entity.series.start_yearinteger or nullrequired: Example: 2018

401

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

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The list is not yours, is not ranked or is built by a rule, or the token holds neither write:list nor write:lists.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

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

404

No live list has this ID.

messagestringrequired: Example: "No query results for model [App\\Models\\UserList] 101"

Example body, from the documented examples

{
  "message": "No query results for model [App\\Models\\UserList] 101"
}

422

The body failed validation.

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

curl --request PUT \
  'https://versedb.com/api/v1/lists/101/items/reorder' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "item_ids": [
    3,
    1,
    2
  ]
}'

Example response 200

{
  "message": "Items reordered successfully.",
  "items": [
    {
      "id": 1,
      "position": 1,
      "note": "Classic!",
      "created_at": "2024-01-15T10:30:00+00:00",
      "updated_at": "2024-01-15T10:30:00+00:00",
      "variant_id": 7,
      "variant": {
        "id": 7,
        "name": "Virgin Variant",
        "ratio": "1:25",
        "cover_image_url": "https://...-cover_md.webp"
      },
      "entity_type": "issues",
      "entity": {
        "id": 5432,
        "slug": "the-amazing-spider-man-1",
        "name": "The 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 Comics",
        "series": {
          "id": 88,
          "name": "The Amazing Spider-Man",
          "slug": "the-amazing-spider-man",
          "start_year": 2018
        }
      }
    }
  ]
}

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.

Query parameters

Responses

Example request

Request body application/json

Responses

Example request

Query parameters

Responses

Example request

Path parameters

Query parameters

Responses

Example request

Path parameters

Query parameters

Responses

Example request

Path parameters

Request body application/json

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Request body application/json

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Request body application/json

Responses

Example request

Path parameters

Request body application/json

Responses

Example request

Path parameters

Responses

Example request

Path parameters

Request body application/json

Responses

Example request

Response headers

Request body `application/json`

Request body `application/json`

Request body `application/json`

Request body `application/json`

Request body `application/json`

Request body `application/json`