{"id":19788294,"url":"https://github.com/weebdatahoarder/stewdio-api","last_synced_at":"2025-07-03T15:36:42.725Z","repository":{"id":113092323,"uuid":"267907825","full_name":"WeebDataHoarder/stewdio-api","owner":"WeebDataHoarder","description":"This is a fork of https://git.sr.ht/~minus/stewdio-api","archived":false,"fork":false,"pushed_at":"2022-01-22T19:36:51.000Z","size":600,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-28T14:39:03.251Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WeebDataHoarder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-29T16:43:52.000Z","updated_at":"2024-02-25T21:01:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"d32d0687-5985-4220-bf8a-aa201e961f96","html_url":"https://github.com/WeebDataHoarder/stewdio-api","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/WeebDataHoarder/stewdio-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeebDataHoarder%2Fstewdio-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeebDataHoarder%2Fstewdio-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeebDataHoarder%2Fstewdio-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeebDataHoarder%2Fstewdio-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WeebDataHoarder","download_url":"https://codeload.github.com/WeebDataHoarder/stewdio-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WeebDataHoarder%2Fstewdio-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263351071,"owners_count":23453399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T06:26:46.823Z","updated_at":"2025-07-03T15:36:42.704Z","avatar_url":"https://github.com/WeebDataHoarder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stewdio API\n\nStewdio API is the central piece of the Stewdio Radio System (SRS). It provides searching and requesting functionality to users and queues songs with the actual streaming daemon (currently only supporting [kawa](https://github.com/Luminarys/kawa)).\n\n\n## Setup\n\n- Install the package (buildable via ArchLinux PKGBUILD in contrib) or via\n  `python setup.py install` (not recommended unless in a venv)\n- Set database connection information and other configuration in\n  `stewdio-api.conf` and/or copy it to `/etc/stewdio/api.conf`\n- Set the database connection information in `alembic.ini`\n- Initialize the database:\n  ```\n  $ PYTHONPATH=\".\" python contrib/init_db.py\n  $ alembic stamp head\n  ```\n- Run `run.sh` to start stewdio-api. Kawa should be running already,\n  otherwise stewdio-api will spit out errors\n\n### Upgrading the database\n`alembic upgrade head`\n\n\n## API\n\n### Restricted API endpoints\nSome restricted API endpoints require an account. Currently, that only includes adding and removing favorites for a user that has a password set.\n\n\n#### Setting a password on users without password\nIf a user was created without a password, a password can only be set using CLI interface. This will generate a random password that can be reset using the *user update* endpoint.\n\n```sh\npython -m stewdio.user \u003cusername\u003e\n```\n\n\n#### Creating a user\nIf no user exists yet, it can be created via the `/api/user/creatwe` endpoint:\n\n```sh\ncurl 'http://localhost:5000/api/user/create' --user minus:asdf -XPOST -s | jq\n```\n\n\n#### Authenticating to user management endpoints\nEndpoints under `/api/user` require authenticating with [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), i.e. username and password must be sent in the `Authorization` header.\n\n\n#### Changing a user password\nTo change a user's password, send a request with the new password to the `/api/user/update` endpoint:\n\n```sh\ncurl 'http://localhost:5000/api/user/create' --user minus:asdf -d '{\"password\":\"newasdf\"}' -s | jq\n```\n\n\n#### Creating API keys\nSome endpoints require an API key. One can be created using the `/api/user/apikeys/create` endpoint by supplying a name for the key (purely informational). The response will contain the API key in the `key` field in the object in the `key` field. This key is just shown once.\n\n```sh\ncurl 'http://localhost:5000/api/user/apikeys/create' --user minus:asdf -d '{\"name\":\"cli request script\"}' -s | jq .key.key\n```\n\n\n#### Authenticating to other endpoints\nSome endpoints, like adding and removing favorites, require an API key to be supplied. The user/password credentials are not accepted. The API key can either be passed via a GET parameter `apikey`, or in the `Authorization` header as *Basic authentication*. Adding the current song to favorites looks as follows:\n\n```sh\ncurl 'http://localhost:5000/api/favorites/minus/playing' --user '\u003capi key\u003e:' -XPUT\ncurl 'http://localhost:5000/api/favorites/minus/playing' --user 'anything:\u003capi key\u003e' -XPUT\ncurl 'http://localhost:5000/api/favorites/minus/playing?apikey=\u003capi key\u003e' -XPUT\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweebdatahoarder%2Fstewdio-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweebdatahoarder%2Fstewdio-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweebdatahoarder%2Fstewdio-api/lists"}