API keys and the OpenAPI spec
Maki has a REST API under /api/v1, the same one the web app uses. Scripts authenticate with a per-user API key.
Create a key
Section titled “Create a key”- Open Settings → Account → API keys.
- Create a key. This asks for your password. Accounts that only use single sign-on need a recent sign-in instead.
- Copy the key when it appears. Maki stores only a SHA-256 hash, so it is never shown again.
Revoke a key from the same card. It stops working on the next request. For keys with two-factor sign-in, see Two-factor and API keys.
Send the key
Section titled “Send the key”Send the key in the X-Api-Key header.
curl -H "X-Api-Key: <your key>" http://localhost:8990/api/v1/series- The header is the only way in. A
?apikey=query parameter is ignored, so the request is unauthenticated. Keys stay out of URLs because they end up in browser history and server logs. - A key has the permissions of the account that created it. Only full-access keys work on
/api/v1. - OPDS tokens and API keys are not interchangeable.
OpenAPI spec and Swagger UI
Section titled “OpenAPI spec and Swagger UI”Swagger UI and the spec are served only in the Development environment. The Docker image runs in Production, so /swagger is not available there.
To browse the spec, run Maki from source. The launch profile in src/Maki.Api/Properties/launchSettings.json sets Development:
dotnet run --project src/Maki.ApiSwagger UI is at http://localhost:8990/swagger and the JSON spec at /swagger/v1/swagger.json.