Skip to content

API v1

KumoYami's JSON API for integrations, the one the Library and Files apps will use (coming soon).

KumoYami has a JSON API, the one its phone and Android TV apps will use (coming soon). Use it to build your own app or to connect your server to other tools. It sees exactly what the site shows the same account, with its permissions.

The basics

  • Address: https://your-server/api/v1/, on either of the server's addresses (Files or the Library).
  • Every path ends with a slash: /api/v1/home/. Without it, the answer is a 308 to the path with it.
  • JSON in and out (Content-Type: application/json on POSTs).
  • No caching (Cache-Control: no-store) and no CORS: it's made for apps, not other websites.
  • Times are milliseconds since 1970; video positions and durations, seconds.
  • File paths (path) are the site's, as they are: /Series/3 Body Problem (2024). Encode them only when you put them in a URL.

First call

curl https://cloud.example.com/api/v1/info/
{
  "name": "KumoYami",
  "version": "0.1.4",
  "api": 1,
  "library": true,
  "users": true,
  "files": true,
  "anonymous": "all",
  "signIn": { "password": true, "passkey": false, "device": true, "patreon": false },
  "features": ["media-library", "profiles", "watch-party"]
}

/info/ needs no session: it says which parts are on, how one can sign in and which features the plan brings.

Finding the server by its code

With the server code, an app asks for the code and looks it up in the license server's directory:

curl https://licenses.kumoyami.com/v1/directory/BCDF-GHJK
{
  "name": "KumoYami",
  "urls": { "files": "https://cloud.example.com", "library": "https://app.example.com" },
  "reachable": { "files": true, "library": true },
  "version": "0.1.4"
}

It's public and needs no session, limited to 30 lookups a minute per IP. Then the app talks to the server directly: keep the address, not the code.

Signing in

Each session is a token: it goes on every request as Authorization: Bearer <token>. It lasts 60 days since its last use, and the account sees it, with the device's name, among its sessions. Cookies are ignored on v1.

The easiest way, with no passwords typed on a TV. It also works with passkeys, Patreon and two-step verification.

curl -X POST https://cloud.example.com/api/v1/auth/device/ \
  -H 'Content-Type: application/json' \
  -d '{ "action": "start", "device": { "name": "Living room TV", "platform": "androidtv" } }'

The answer carries userCode (for example BCDF-GHJK) and verificationUri. Show them (and a QR code of verificationUriComplete). The person opens them on their phone, where they're already signed in, and approves. Meanwhile, ask every interval seconds with { "action": "poll", "deviceCode": "…" } until you get "status": "approved" and the token.

POST /auth/logout/ closes the session: the token and every address signed for it stop working.

The parts

PartRoutesNeeds
Server/info/Nothing
Sign-in/auth/*, /me/, /profiles/Accounts switched on
Library/home/, /libraries/, /browse/, /title/, /search/, /play/, /progress/, /watched/, /watchlist/, /history/, /requests/*, /downloads/…The Library on, and a token of an account let into it
Files/files/list/, /files/search/, /files/download/, /files/preview/, /files/unlock/Nothing else; the token is optional
Media/media/<kind>/A signed address

If a part isn't available, its routes answer 403 with code: "license" (not in the plan) or "disabled" (switched off in the panel).

The most used

  • GET /home/: the rows of the Library's home page (Continue watching, Recently added…).
  • GET /libraries/ and GET /browse/?library=: the libraries and their content, by pages (cursor).
  • GET /title/?path=: the page of a film, series, season or episode.
  • GET /play/?path=: how to play a video (direct or converted, with its tracks and subtitles).
  • POST /progress/: where playback is, for Continue watching.
  • GET /profiles/ and POST /profiles/: picking a profile, with its PIN if it has one.

Signed addresses

Pictures, videos, subtitles and downloads come as absolute, signed addresses, so image and video components load them without headers:

https://cloud.example.com/api/v1/media/<kind>/?path=…&ks=<signature>

They expire by themselves (pictures in 6 to 12 hours, videos after their length plus 2 hours) and stop working when the session closes. Treat them as secrets: they open that file until they expire.

Errors

{ "error": "Human-readable message (English)", "code": "machine_code" }
StatuscodeWhat's going on
400bad_requestA parameter is missing or invalid.
401authNo token, or it's no longer valid.
403forbidden, password, profileThe account can't open it, the folder's password is needed, or the profile isn't old enough.
403license, disabledThe part isn't in the plan, or it's switched off.
404not_foundIt doesn't exist, or can't be seen.
409profile_requiredA profile has to be picked first.
429rate_limited, too_many_playbacksToo many attempts, or too many videos at once.
5xxserver, storageA server or storage error.

Accept-Language picks the language of titles, synopses and the API's few texts (es, en and others).

Building an app?

Write to us (the address is in the legal notice) and we'll send you the full API reference, with every route, its answers and examples.

All trademarks and logos belong to their respective owners. Their use only indicates compatibility, not sponsorship or affiliation. The Synology logo is a trademark of Synology Inc.; Google Drive, Google Cast and Android are trademarks of Google LLC, and the Android robot is reproduced from work created and shared by Google, used under the Creative Commons Attribution 3.0 license. Microsoft, Windows and OneDrive are trademarks of the Microsoft group of companies; Amazon S3 is a trademark of Amazon.com, Inc. or its affiliates; Apple, AirPlay, macOS and iPhone are trademarks of Apple Inc.; Raspberry Pi is a trademark of Raspberry Pi Ltd; Ubuntu is a trademark of Canonical Ltd.; Debian is a trademark of Software in the Public Interest, Inc.; Linux is a trademark of Linus Torvalds. This product uses the TMDB API but is not endorsed or certified by TMDB.