Collectoh
EN

This page is in English only for now. The main pages follow your choice.

Sign up free
Browse the docs

API reference

Watchlist and friends

A watchlist across every streaming service (P6-49), and ratings, reviews and friends’ activity on this server (P6-50). Friends are the people on the same server; each shares only what they choose (sharing in their preferences), and nobody sees anything about an item they couldn’t open themselves.

Paths are relative to /api/v1 on your server.

GET/friends#

The people on this server, and what each shares

Yourself first. sharing is your own choice, as your preferences hold it.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/friends/{id}#

One person’s page

Their activity, reviews and ratings as you may see them, and their watchlist while they share it.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
beforequerystring
limitqueryinteger
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: nobody by that id is on this server application/json · ErrorEnvelope
GET/friends/activity#

What people here watched, rated, reviewed and put on their watchlists

Newest first, a page at a time: before is the next of the page before. Only what each person shares, and only about items you may open; a review is always shown, being written to be read. Nothing from an adult library.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
beforequerystring
limitqueryinteger
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
GET/items/{id}/opinions#

An item’s ratings and reviews

Your rating, the average of every rating you see (yours, those shared, those with a review), each shared rating, and the reviews. open is false for what can’t be rated: anything but a film, show or episode, or anything in an adult library.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
PUT/items/{id}/rating#

Rate an item

Half stars, 1 to 10; null clears it.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: it can’t be rated application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
PUT/items/{id}/review#

Write or rewrite your review of an item

Up to 5,000 characters; spoilers hides it until the reader asks. Everyone on this server who may open the item can read it.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: it can’t be reviewed application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
DELETE/items/{id}/review#

Take your review down

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: you haven’t reviewed it application/json · ErrorEnvelope
DELETE/reviews/{id}#

Take a review down

Its author, or whoever runs the server (user:manage).

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. FORBIDDEN: it isn’t yours, and you don’t run the server application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: no such review application/json · ErrorEnvelope
GET/watchlist#

Your watchlist

Newest first. onServer is this server’s copy, when it has one you may open: the one it was added from, or one found since by its TMDB number. A catalogue title is left out for an account with an age limit, since nobody vouches for its rating, and for an account with Discover switched off (P7-20), which keeps to what is on the server; its catalogue titles come back with Discover.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/watchlist#

Put a title on your watchlist

A title from Discover ({tmdb: {kind, id}}) or a film or show of this server’s ({itemId}). 201 when added, 200 with the entry it already had.

Authorisation
Bearer token or API key · Session cookie
Body
application/json ·
  • 201Success. application/json · object
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. PERMISSION_AGE_RESTRICTED: a catalogue title (none of this server’s), for an account with an age limit FORBIDDEN: a catalogue title, with Discover switched off for the account (details.reason is discover-off) application/json · ErrorEnvelope
  • 404NOT_FOUND: no such title or item, or it is past your age limit application/json · ErrorEnvelope
  • 409CONFLICT: the watchlist holds 1,000 titles already application/json · ErrorEnvelope
  • 502PROVIDER_UNAVAILABLE: a catalogue title, on a server that asks no film catalogue application/json · ErrorEnvelope
DELETE/watchlist/{id}#

Take a title off your watchlist

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 404NOT_FOUND: no such thing, or not one the caller may see. NOT_FOUND: it isn’t on your watchlist application/json · ErrorEnvelope
GET/watchlist/availability#

Where each title on your watchlist can be watched

By entry, in your country: subscription, free, rent or buy, as TMDB has JustWatch’s data, and when it comes out. TMDB’s answers are kept twelve hours.

Authorisation
Bearer token or API key · Session cookie
  • 200Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope