tiddl-rest-api

REST API for downloading Tidal tracks via tiddl.

Install (NixOS + SOPS)

# flake.nix
{
  inputs.tiddl-rest-api.url = "git+https://git.sid.ovh/sid/tiddl-rest-api.git";

  outputs = { nixpkgs, tiddl-rest-api, ... }: {
    nixosConfigurations.host = nixpkgs.lib.nixosSystem {
      modules = [
        tiddl-rest-api.nixosModules.default
        ({ pkgs, ... }: {
          nixpkgs.overlays = [ tiddl-rest-api.overlays.default ];

          services.tiddl-api = {
            enable = true;
            port = 8080;
            downloadPath = "/data/tidal";
            authFile = config.sops.secrets."tiddl/auth".path;
            apiTokensFile = config.sops.templates."tiddl/api-tokens".path;
          };
        })
      ];
    };
  };
}

SOPS secrets:

# tiddl/auth    -- output of `tiddl auth login` placed on the server
# tiddl/api-tokens  -- one bearer token per line
tk_user1_abc123
tk_bot2_xyz789

Run tiddl auth login once on any machine with a browser. Copy the resulting auth.json to the server. The refresh token is long-lived; access tokens auto-refresh.

API

All endpoints except /health require Authorization: Bearer <token>.

POST /download        {"url": "https://tidal.com/browse/track/123"}
                      -> 202 {"task_id": "...", "status": "queued"}

GET  /task/{id}       -> {"status": "completed", "files": ["/data/tidal/..."], "tracks": [...]}

GET  /health          -> {"status": "ok", "tidal_authenticated": true}

GET  /track/{id}
GET  /album/{id}
GET  /playlist/{uuid}
GET  /search?q=artist+track&limit=10

Tracks, albums, playlists, and artist URLs are supported. Single tracks return immediately; albums and playlists run as async tasks. Files stay on the server; responses include paths.

CLI

nix run .#tiddl-cli -- --api-url https://tdl.sid.ovh --api-token <token> status

# Download from URL or type/id
tiddl-cli download album/423929914
tiddl-cli download https://tidal.com/browse/track/1550546

# Search and inspect metadata
tiddl-cli search "daft punk" --limit 5
tiddl-cli track 1550546

# Config stored at ~/.config/tiddl/config.toml
tiddl-cli config set --api-url https://tdl.sid.ovh --api-token <token>

Config priority: flags > TIDDL_API_URL/TIDDL_API_TOKEN env > config file.