Collectoh
EN

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

Sign up free
Browse the docs

API reference

Import

A household brought over from Plex, Jellyfin or Emby (P7-06): the other server connected with its owner’s token or an API key, kept sealed and never returned; its people offered as accounts here, invitations or nothing (never accounts made with passwords); its libraries’ folders offered, never mounted; and an import that reads — never writes — each person’s watched state, positions, ratings, favourites and playlists and the collections, matched here by the ids both sides hold. An admin sees counts of anyone’s state, never titles. user:manage.

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

PUT/import/items/{id}/ignored#

Leave an item out, or put it back

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. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks user:manage, 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/import/items/{id}/match#

Match an item by hand

To an item here of the same kind; a show’s episodes and an album’s tracks follow it by number. What waited on it is brought at once, as an import would.

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. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks user:manage, 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/import/items/{id}/match#

Take a match back

What it brought here stays.

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 user:manage, 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
POST/import/runs/{id}/cancel#

Stop an import

A queued one is taken off the queue; a running one stops at its next step. What it brought stays.

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 user:manage, 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
  • 409CONFLICT: it has finished application/json · ErrorEnvelope
GET/import/sources#

The servers connected to import from

Each with its libraries and their folders, its people and what was chosen for each, the latest run, and how many of its items matched here. Never a token: hasToken says one is kept.

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 user:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/import/sources#

Connect a Plex, Jellyfin or Emby server

Its owner’s X-Plex-Token, or an API key Jellyfin or Emby made, is checked against the server, then kept sealed on this server for the imports that follow. Its people and libraries are read; Plex’s from plex.tv as well, or the owner alone when plex.tv can’t be reached (plex-tv-unreachable). 201 when new; 200 when the same server was connected before, which keeps the choices made for it.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 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 user:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 502PROVIDER_UNAVAILABLE: the server can’t be reached, or answers unreadably application/json · ErrorEnvelope
GET/import/sources/{id}#

One server connected to import from

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 user:manage, 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
PATCH/import/sources/{id}#

Change its token or address, forget its token, choose its libraries

A new token or address is checked against the server first, and must lead to the same one. libraries says which of its libraries an import reads, and which library here was made from each.

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. application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks user:manage, 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
  • 409CONFLICT: the address now leads to another server application/json · ErrorEnvelope
  • 502PROVIDER_UNAVAILABLE: the server can’t be reached application/json · ErrorEnvelope
DELETE/import/sources/{id}#

Forget a server

Its kept token, people, items, held state and runs go. What was brought here stays: watched state, ratings, favourites, playlists and collections are the people’s and the server’s now.

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 user:manage, 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
  • 409CONFLICT: an import of it is running application/json · ErrorEnvelope
GET/import/sources/{id}/items#

What didn’t match here, to match by hand

A page at a time (cursor is the next of the page before). An episode whose show has no match is not listed on its own: the show is, with how many follow it (children); a track and its album likewise. waiting says something — someone’s state, a playlist, a collection — waits on the item, never whose.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
statusquery"unmatched" | "matched" | "ignored"
kindquery"movie" | "show" | "episode" | "artist" | "album" | "track"
qquerystring
waitingquery
cursorquerystring
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 user:manage, 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/import/sources/{id}/people/{personId}#

Choose what becomes of someone

map brings their state to an account here; invite makes an invitation through the ordinary invitations (its link returned here once, as POST /invites does) and holds their state until it is accepted; skip reads nothing of theirs. Nobody is made an account with a password.

Authorisation
Bearer token or API key · Session cookie
Body
application/json ·
ParameterInTypeDescription
id requiredpathstring (uuid)
personId requiredpathstring (uuid)
  • 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 user:manage, 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
POST/import/sources/{id}/refresh#

Read its people and libraries again

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 user:manage, 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
  • 409CONFLICT: the address now leads to another server application/json · ErrorEnvelope
  • 502PROVIDER_UNAVAILABLE: the server can’t be reached application/json · ErrorEnvelope
GET/import/sources/{id}/runs#

Every import of a server, with what each did

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 user:manage, 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
POST/import/sources/{id}/runs#

Start an import

A job, one at a time: reads the other server (never writing to it), matches its items here by the ids both sides hold, reads each chosen person’s watched state, positions, ratings, favourites and playlists and the collections, and brings each person’s to their account — later wins, by when, and nothing twice — or holds it for their invitation. How far it got is on the run.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring (uuid)
  • 202Success. application/json · object
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks user:manage, 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
  • 409CONFLICT: an import of this server is already running application/json · ErrorEnvelope