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 a308to the path with it. - JSON in and out (
Content-Type: application/jsonon 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
| Part | Routes | Needs |
|---|---|---|
| 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/andGET /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/andPOST /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" }| Status | code | What's going on |
|---|---|---|
| 400 | bad_request | A parameter is missing or invalid. |
| 401 | auth | No token, or it's no longer valid. |
| 403 | forbidden, password, profile | The account can't open it, the folder's password is needed, or the profile isn't old enough. |
| 403 | license, disabled | The part isn't in the plan, or it's switched off. |
| 404 | not_found | It doesn't exist, or can't be seen. |
| 409 | profile_required | A profile has to be picked first. |
| 429 | rate_limited, too_many_playbacks | Too many attempts, or too many videos at once. |
| 5xx | server, storage | A 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.