social.popfeed.feed.listItem

bookhive.buzz

Documentation

main record

No description available.

Record Key tid Timestamp-based ID

Properties

addedAt string datetime Required

Timestamp when the creative work was added to the list.

backdrop blob Optional

No description available.

maxSize: 4.0 MB

backdropUrl string uri Optional

Backdrop image URL for the creative work. Soon to be deprecated in favor of the 'backdrop' blob field

bookProgress ref #bookProgress Optional

Reading progress for books or book series (also supports audiobooks via time fields).

completedAt string datetime Optional

Timestamp when the user finished the creative work. Most relevant for books, TV shows, and video games.

creativeWorkType string Required

The type of creative work this item represents.

Allowed: movie, tv_show, video_game, album, book, book_series, episode, album, ep, tv_season, tv_episode, track

description string Optional

Optional description or commentary for the list item.

maxLength: 5000 bytes

genres array of string Optional

No description available.

identifiers ref #identifiers Required

External identifiers for the creative work.

listType string Optional

The type of list, e.g., 'watchlist', 'favorites', 'to-read', etc.

maxLength: 50 bytes

listUri string uri Required

URI of the list where the item is stored.

mainCredit string Optional

Main actor, director, author, or artist of the creative work.

maxLength: 1000 bytes

mainCreditRole string Optional

The role of the main credit.

Allowed: director, author, artist, showrunner, lead_actor, creator, studio, publisher, developer, performer, network

position integer Optional

DEPRECATED

poster blob Optional

No description available.

maxSize: 2.0 MB

posterUrl string uri Optional

Poster or cover image URL for the creative work. Soon to be deprecated in favor of the 'poster' blob field

releaseDate string datetime Optional

Release date of the creative work.

startedAt string datetime Optional

Timestamp when the user started the creative work. Most relevant for books, TV shows, and video games.

status string Optional

No description available.

Known values: #finished, #in_progress, #backlog, #abandoned

title string Optional

Title of the creative work.

maxLength: 1000 bytes

watchedEpisodes array of ref #watchedEpisode Optional

For TV shows, the episodes the user has watched.

View raw schema

{
  "key": "tid",
  "type": "record",
  "record": {
    "type": "object",
    "required": [
      "identifiers",
      "creativeWorkType",
      "addedAt",
      "listUri"
    ],
    "properties": {
      "title": {
        "type": "string",
        "maxLength": 1000,
        "description": "Title of the creative work."
      },
      "genres": {
        "type": "array",
        "items": {
          "type": "string",
          "maxLength": 50
        }
      },
      "poster": {
        "type": "blob",
        "accept": [
          "image/*"
        ],
        "maxSize": 2000000
      },
      "status": {
        "type": "string",
        "knownValues": [
          "#finished",
          "#in_progress",
          "#backlog",
          "#abandoned"
        ]
      },
      "addedAt": {
        "type": "string",
        "format": "datetime",
        "description": "Timestamp when the creative work was added to the list."
      },
      "listUri": {
        "type": "string",
        "format": "uri",
        "description": "URI of the list where the item is stored."
      },
      "backdrop": {
        "type": "blob",
        "accept": [
          "image/*"
        ],
        "maxSize": 4000000
      },
      "listType": {
        "type": "string",
        "maxLength": 50,
        "description": "The type of list, e.g., 'watchlist', 'favorites', 'to-read', etc."
      },
      "position": {
        "type": "integer",
        "description": "DEPRECATED"
      },
      "posterUrl": {
        "type": "string",
        "format": "uri",
        "description": "Poster or cover image URL for the creative work. Soon to be deprecated in favor of the 'poster' blob field"
      },
      "startedAt": {
        "type": "string",
        "format": "datetime",
        "description": "Timestamp when the user started the creative work. Most relevant for books, TV shows, and video games."
      },
      "mainCredit": {
        "type": "string",
        "maxLength": 1000,
        "description": "Main actor, director, author, or artist of the creative work."
      },
      "backdropUrl": {
        "type": "string",
        "format": "uri",
        "description": "Backdrop image URL for the creative work. Soon to be deprecated in favor of the 'backdrop' blob field"
      },
      "completedAt": {
        "type": "string",
        "format": "datetime",
        "description": "Timestamp when the user finished the creative work. Most relevant for books, TV shows, and video games."
      },
      "description": {
        "type": "string",
        "maxLength": 5000,
        "description": "Optional description or commentary for the list item."
      },
      "identifiers": {
        "ref": "#identifiers",
        "type": "ref",
        "description": "External identifiers for the creative work."
      },
      "releaseDate": {
        "type": "string",
        "format": "datetime",
        "description": "Release date of the creative work."
      },
      "bookProgress": {
        "ref": "#bookProgress",
        "type": "ref",
        "description": "Reading progress for books or book series (also supports audiobooks via time fields)."
      },
      "mainCreditRole": {
        "enum": [
          "director",
          "author",
          "artist",
          "showrunner",
          "lead_actor",
          "creator",
          "studio",
          "publisher",
          "developer",
          "performer",
          "network"
        ],
        "type": "string",
        "description": "The role of the main credit."
      },
      "watchedEpisodes": {
        "type": "array",
        "items": {
          "ref": "#watchedEpisode",
          "type": "ref"
        },
        "description": "For TV shows, the episodes the user has watched."
      },
      "creativeWorkType": {
        "enum": [
          "movie",
          "tv_show",
          "video_game",
          "album",
          "book",
          "book_series",
          "episode",
          "album",
          "ep",
          "tv_season",
          "tv_episode",
          "track"
        ],
        "type": "string",
        "description": "The type of creative work this item represents."
      }
    }
  }
}

bookProgress object

Tracks reading/listening progress for a book or book series item.

Properties

currentChapter integer Optional

Current chapter number (optional alternative to pages).

currentPage integer Optional

Current page number (if applicable).

percent integer Optional

Optional explicit progress percentage (0–100).

status string Required

Overall progress state.

totalChapters integer Optional

Total chapters (if known).

totalPages integer Optional

Total pages (if known).

updatedAt string datetime Required

Last time progress was updated.

View raw schema

{
  "type": "object",
  "required": [
    "status",
    "updatedAt"
  ],
  "properties": {
    "status": {
      "enum": [
        "in_progress",
        "completed",
        "paused"
      ],
      "type": "string",
      "description": "Overall progress state."
    },
    "percent": {
      "type": "integer",
      "description": "Optional explicit progress percentage (0–100)."
    },
    "updatedAt": {
      "type": "string",
      "format": "datetime",
      "description": "Last time progress was updated."
    },
    "totalPages": {
      "type": "integer",
      "description": "Total pages (if known)."
    },
    "currentPage": {
      "type": "integer",
      "description": "Current page number (if applicable)."
    },
    "totalChapters": {
      "type": "integer",
      "description": "Total chapters (if known)."
    },
    "currentChapter": {
      "type": "integer",
      "description": "Current chapter number (optional alternative to pages)."
    }
  },
  "description": "Tracks reading/listening progress for a book or book series item."
}

identifiers object

No description available.

Properties

asin string Optional

Amazon Standard ID

episodeNumber integer Optional

Episode number for TV shows or series

hiveId string Optional

BookHive ID for fast local lookup

igdbId string Optional

IGDB ID for games

imdbId string Optional

IMDb ID

isbn10 string Optional

ISBN-10 for books

isbn13 string Optional

ISBN-13 for books

mbId string Optional

DEPRECATED - soon to be ignored

mbReleaseId string Optional

MusicBrainz ID for specific releases (albums, EPs, tracks)

other string Optional

Other external ID

parentMbReleaseId string Optional

MusicBrainz ID for parent release (e.g., album for a track)

seasonNumber integer Optional

Season number for TV shows or series

tmdbId string Optional

TMDb ID for movies/TV shows

tmdbTvSeriesId string Optional

TMDb ID for TV series

View raw schema

{
  "type": "object",
  "properties": {
    "asin": {
      "type": "string",
      "description": "Amazon Standard ID"
    },
    "mbId": {
      "type": "string",
      "description": "DEPRECATED - soon to be ignored"
    },
    "other": {
      "type": "string",
      "description": "Other external ID"
    },
    "hiveId": {
      "type": "string",
      "description": "BookHive ID for fast local lookup"
    },
    "igdbId": {
      "type": "string",
      "description": "IGDB ID for games"
    },
    "imdbId": {
      "type": "string",
      "description": "IMDb ID"
    },
    "isbn10": {
      "type": "string",
      "description": "ISBN-10 for books"
    },
    "isbn13": {
      "type": "string",
      "description": "ISBN-13 for books"
    },
    "tmdbId": {
      "type": "string",
      "description": "TMDb ID for movies/TV shows"
    },
    "mbReleaseId": {
      "type": "string",
      "description": "MusicBrainz ID for specific releases (albums, EPs, tracks)"
    },
    "seasonNumber": {
      "type": "integer",
      "description": "Season number for TV shows or series"
    },
    "episodeNumber": {
      "type": "integer",
      "description": "Episode number for TV shows or series"
    },
    "tmdbTvSeriesId": {
      "type": "string",
      "description": "TMDb ID for TV series"
    },
    "parentMbReleaseId": {
      "type": "string",
      "description": "MusicBrainz ID for parent release (e.g., album for a track)"
    }
  }
}

watchedEpisode object

No description available.

Properties

episodeNumber integer Required

No description available.

seasonNumber integer Required

No description available.

tmdbId string Optional

No description available.

View raw schema

{
  "type": "object",
  "required": [
    "seasonNumber",
    "episodeNumber"
  ],
  "properties": {
    "tmdbId": {
      "type": "string"
    },
    "seasonNumber": {
      "type": "integer"
    },
    "episodeNumber": {
      "type": "integer"
    }
  }
}