Collectoh
EN

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

Sign up free
Browse the docs

API reference

Backup

Backups, restore and personal data export (P3-18).

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

GET/backup#

List backups

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

Make a backup

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 201Success. application/json · BackupRecord
  • 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 settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
DELETE/backup/{id}#

Delete a backup

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring
  • 204Done; no body.
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings: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
GET/backup/{id}/download#

Download a backup

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
id requiredpathstring
  • 200Success. application/zstd ·
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings: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
GET/backup/offsite#

Off-site backups: how they stand

Plus (P6-22). Whether this server can send its backups off-site — claimed by a Collectoh account with Plus — whether each scheduled backup goes, whether a passphrase is set, and how the last send went.

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

Send each scheduled backup off-site, or stop

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 200Success. application/json · OffsiteStatus
  • 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
  • 402PLUS_REQUIRED: The account has no Plus. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 409CONFLICT: Switched on before this server is claimed by a Collectoh account (details.reason is claim), or before a passphrase is chosen (passphrase). application/json · ErrorEnvelope
GET/backup/offsite/backups#

The account’s off-site backups

From every server the account has had, newest first: what a new install restores from.

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 settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/backup/offsite/backups/{id}/restore#

Restore an off-site backup

Fetched, opened with the passphrase and checked as a backup on this disk is, then restored unless dryRun. This install keeps its own claim, and the key the passphrase made, so later backups go off-site as before.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
ParameterInTypeDescription
id requiredpathstring
  • 200Success. application/json · RestoreReport
  • 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: The passphrase does not open it (details.reason is passphrase), or it has been damaged (damaged), cut short (truncated) or is not one (format). application/json · ErrorEnvelope
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings: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/backup/offsite/passphrase#

Choose the off-site passphrase

The key it makes (scrypt) seals every backup sent off-site. The key is kept here, sealed with SECRET_KEY; the passphrase is kept nowhere and never sent. Backups sealed under an earlier passphrase still need that one.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 200Success. application/json · OffsiteStatus
  • 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 settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
POST/backup/offsite/send#

Send a backup off-site now

The database and its settings — never media, never artwork — sealed here and kept on collectoh.com for 30 days.

Authorisation
Bearer token or API key · Session cookie
  • 201Success. application/json · OffsiteSent
  • 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
  • 402PLUS_REQUIRED: The account has no Plus, or Plus covers three other servers. application/json · ErrorEnvelope
  • 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
  • 409CONFLICT: This server is not claimed, or no passphrase is chosen. application/json · ErrorEnvelope
GET/export#

Export my data

What the account owns — history, notes, playlists — as a JSON download.

Authorisation
Bearer token or API key · Session cookie
ParameterInTypeDescription
scopequery"history" | "progress" | "playlists" | "notes" | "metadata"
  • 200Success. application/json ·
  • 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
POST/restore#

Restore a backup

dryRun reports what would happen without touching anything.

Authorisation
Bearer token or API key · Session cookie
Body
application/json · object
  • 200Success. application/json · RestoreReport
  • 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 settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope