{ "openapi": "3.0.0", "paths": { "/api": { "get": { "operationId": "AppController_apiHome", "summary": "Get information about your API.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "Lists all available versions of your API, and all endpoints across all versions of your API.", "content": { "application/json": { "schema": { "example": { "versions": { "v1": "/api/v1" }, "endpoints": [ "GET /api/v1/health" ] } } } } } }, "tags": [ "General" ] } }, "/api/v1/health": { "get": { "operationId": "AppController_getHealth", "summary": "Know if your Media Server is online.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "Returns the state of the server. If the server responds, then it's online.\n Responses will always have a 200 status. Possible states are: \n `normal`, `not_setup.`", "content": { "application/json": { "schema": { "example": { "state": "normal" } } } } } }, "tags": [ "General" ] } }, "/api/v1/release-channels": { "get": { "operationId": "AppController_getCurrentReleaseChannel", "summary": "Get the current release channel.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } } }, "tags": [ "General" ] } }, "/api/v1/updates": { "get": { "operationId": "AppController_getAvailableUpdates", "summary": "Manually check for available updates.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "example": { "updateIsAvailable": true, "daysBehindLatestVersion": 42, "latestVersion": "0.0.1", "latestVersionReleasedAt": "Thu Jan 04 2024 21:28:00 GMT-0500 (Eastern Standard Time)" } } } } }, "503": { "description": "Returns a 503 if the latest version cannot be fetched from the cloud, or if the server is running in development mode." } }, "tags": [ "General" ] } }, "/api/v1/setup": { "post": { "operationId": "AppController_setup", "summary": "Initial setup.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerSetupDto" } } } }, "responses": { "201": { "description": "Returns an empty Created response on success." }, "403": { "description": "Possible reasons: The initial setup has already been completed." } }, "tags": [ "General" ] } }, "/api/v1/instance": { "get": { "operationId": "AppController_getInstance", "summary": "Get information about this server instance.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "example": { "instanceId": "", "serverName": "My custom name", "kioskMode": false } } } } } }, "tags": [ "General" ] } }, "/api/v1/versions": { "get": { "operationId": "AppController_getAppVersions", "summary": "Get versions of things.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "example": { "nodejs": "0.0.0", "openssl": "0.0.0", "database": "0.0.0", "cardinal_media_server": "0.0.0", "cardinal_media_server_web_app": "0.0.0", "cardinal_music_web_app": "0.0.0", "cardinal_photos_web_app": "0.0.0", "cardinal_cinema_web_app": "0.0.0", "build_tag": "--" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." } }, "tags": [ "General" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/reset": { "post": { "operationId": "AppController_reset", "summary": "🛡️ Reset server state.", "description": "Deindexing media requires the `Indexing.Deindex` capability; a factory reset requires `MediaServer.FactoryReset`. Both types are gated behind a validation phrase that the user must type out: `Deindex media` and `Factory reset` respectively.

🛡️ Requires one of these Capabilities: Indexing.Deindex MediaServer.FactoryReset

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerResetDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The validation phrase does not match the reset type." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user lacks the capability for the requested reset type." } }, "tags": [ "General" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/ls": { "get": { "operationId": "AppController_ls", "summary": "List the contents of a directory.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "rootDir", "required": true, "in": "query", "schema": { "enum": [ "music", "photos", "movies", "tv" ], "type": "string" } }, { "name": "path", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "removeFileNodes", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "addEmptyNodes", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; Missing root directory." }, "401": { "description": "Possible reasons: The authorization token is invalid." } }, "tags": [ "General" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/dev/settings/{app}/{key}": { "get": { "operationId": "DevController_getSetting", "summary": "Dev-only: read a settings value for the given app.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "app", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/last-claim-attempt": { "get": { "operationId": "DevController_lastClaimAttempt", "summary": "Dev-only: read the in-memory record of the most recent claim attempt.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/factory-reset": { "post": { "operationId": "DevController_factoryReset", "summary": "Dev-only: factory-reset the server without the validation phrase.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/options/{name}": { "get": { "operationId": "DevController_readOption", "summary": "Dev-only: read a server option by name.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "name", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/first-time-setup": { "post": { "operationId": "DevController_firstTimeSetup", "summary": "Dev-only: complete first-time-setup without driving the wizard.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/users/local": { "post": { "operationId": "DevController_createLocalUser", "summary": "Dev-only: create a local user with the given role.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/users/{userId}": { "delete": { "operationId": "DevController_deleteLocalUser", "summary": "Dev-only: delete a user by userId.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/users/grant-role": { "post": { "operationId": "DevController_grantRole", "summary": "Dev-only: grant a role to a user.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/users/revoke-role": { "post": { "operationId": "DevController_revokeRole", "summary": "Dev-only: revoke a role from a user.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/libraries": { "post": { "operationId": "DevController_createLibrary", "summary": "Dev-only: insert a library row directly.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/dev/libraries/{libraryId}": { "delete": { "operationId": "DevController_deleteLibrary", "summary": "Dev-only: delete a library by libraryId.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "libraryId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Dev" ] } }, "/api/v1/auth/login": { "post": { "operationId": "LoginController_login", "summary": "🛡️ Log into a Cardinal app.", "description": "Logs the user into a client application that is hosted (bundled web app) or served by this server.\n\nIf logging into the Guest Account, no credentials are required. If logging into a Cardinal Account, a valid Cardinal SSO token is required.\n\nThe client app must set the cardinal-app header for this request.\n\nOnly the capability corresponding to the application that you are trying to log into will be validated.\n\nA same-site login also receives the httpOnly refresh cookie. A cross-site login (a Cardinal-hosted app reaching this server through Remote Access, detected with Sec-Fetch-Site or the Origin header) receives no cookie, since the browser would never send it back; that session is kept alive by the Cardinal Account token instead, see /auth/refresh.

🛡️ Requires one of these Capabilities: AdminApp.Login MusicApp.Login PhotosApp.Login CinemaApp.Login

", "parameters": [ { "name": "cardinal-app", "in": "header", "schema": { "enum": [ "admin", "music", "photos", "cinema" ], "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDetails" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "description": "Returns a 401 if there is an issue with the SSO token." }, "503": { "description": "The Cardinal cloud could not be reached to verify the SSO token (code cloud_unavailable)." } }, "tags": [ "Authentication" ] } }, "/api/v1/auth/refresh": { "post": { "operationId": "LoginController_refresh", "summary": "Refresh the access token using the httpOnly cookie, or a linked Cardinal Account token from another site.", "description": "Issues a new short-lived access token.\n\nSame-site callers (the bundled web apps, or any app served from one of this server's own hostnames) send the httpOnly refresh cookie that /auth/login set. The cookie is rotated on every refresh, and its lifetime follows the Admin app's Session timeout setting.\n\nCross-site callers (a Cardinal-hosted app reaching this server through Remote Access) have no cookie to send, so they send the CardinalTolkien header instead. When the Cardinal cloud vouches for that token and the cloud account is linked to an account on this server, a new access token is issued for the linked account and no cookie is set. That session lasts as long as the Cardinal Account's own session does; the Session timeout setting does not apply to it.\n\nA cloud-linked account is validated against the cloud on every refresh, whichever credential it sent.

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid; A cloud-linked account sent no cloud token, or one the cloud no longer accepts (code cloud_token_required). The local session is unaffected: sign back into the Cardinal account and retry; A cross-site caller sent a cloud token whose Cardinal account is not linked to an account on this server (no code)." }, "503": { "description": "The Cardinal cloud could not be reached to verify a cloud-linked account (code cloud_unavailable). Nothing about the session has changed." } }, "tags": [ "Authentication" ] } }, "/api/v1/auth/logout": { "post": { "operationId": "LoginController_logout", "summary": "Clear the refresh token cookie.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "201": { "description": "" } }, "tags": [ "Authentication" ] } }, "/api/v1/cors-origins": { "get": { "operationId": "CorsController_getCorsOrigins", "summary": "🛡️ Get the custom CORS origins.", "description": "Get the user-configured origins that are allowed to use the API, in addition to the built-in allowlist.

🛡️ Requires Capabilities: ServerSettings.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CorsOrigin" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "CORS Origins" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "post": { "operationId": "CorsController_addCorsOrigin", "summary": "🛡️ Add a custom CORS origin.", "description": "

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCorsOriginDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorsOrigin" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The origin is not a well-formed http(s) URL." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "CORS Origins" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/cors-origins/{id}": { "delete": { "operationId": "CorsController_deleteCorsOrigin", "summary": "🛡️ Delete a custom CORS origin.", "description": "

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "CORS Origins" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/invitations/{id}": { "get": { "operationId": "InvitationController_getInvitation", "summary": "🛡️ Get data about an invitation.", "description": "

🛡️ Requires Capabilities: Invitations.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Invitations" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "InvitationController_deleteInvitation", "summary": "🛡️ Revoke an invitation.", "description": "

🛡️ Requires Capabilities: Invitations.Delete

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Invitations" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/invitations": { "get": { "operationId": "InvitationController_queryInvitations", "summary": "🛡️ Query invitations.", "description": "Returns every invitation this server has, newest first, including the spent and expired ones. Filter with status.

🛡️ Requires Capabilities: Invitations.Read

", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "active", "bound", "claimed", "expired", "revoked" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Invitations" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "post": { "operationId": "InvitationController_createInvitation", "summary": "🛡️ Create a new invitation.", "description": "Creates a single-use invitation granting the given role. Requires the cloud account JWT header: the first invitation this server ever creates issues its invitations credential from Cardinal Cloud, which only the server owner can do.

With targetPublicUserId the invitation is addressed to that one Cardinal account instead of being a shareable link: Cardinal Cloud emails the account an approval link, and the response carries no shortcode and no url because a direct invitation has neither.

🛡️ Requires Capabilities: Invitations.Create

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The cloud account JWT header is missing." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; This server holds no invitations credential yet and the caller is not its owner." }, "404": { "description": "No Cardinal account can be invited under the given targetPublicUserId. The body carries the code target_unavailable and deliberately says no more." }, "409": { "description": "Cardinal Cloud refused the creation. The body carries the cloud's code: daily_invitation_limit when the account has created 20 invitations in the trailing 24 hours." } }, "tags": [ "Invitations" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/settings/{app}": { "get": { "operationId": "SettingsController_getAppSettings", "summary": "Get app settings.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "app", "required": true, "in": "path", "description": "The Cardinal app to get settings for.", "schema": { "enum": [ "admin", "music", "photos", "cinema" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAppSettingsResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." } }, "tags": [ "Settings" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/settings": { "patch": { "operationId": "SettingsController_upsertSettings", "summary": "🛡️ Save app settings.", "description": "When saving app settings, set the `app` for which this update applies. Explicitly set the app to `null` to apply the update to all apps. Account-scoped settings ignore `app` entirely and are always saved against the caller; settings that belong to the whole install require the `ServerSettings.Update` capability.

🛡️ Requires one of these Capabilities: ServerSettings.Update

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSettings" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertSettingsResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The payload changes a setting that belongs to the whole server and the user lacks ServerSettings.Update." } }, "tags": [ "Settings" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/events/subscribe": { "get": { "operationId": "EventController_sse", "summary": "Subscribe to real time events.", "description": "Subscribe to events. An `EventSource` can be used to listen to events (the\nSwagger test page won't work).\n\nEach client connection is unique to that client app, and clients will only\nreceive the events that are meant for them.\n\nAuthenticate with the standard `Authorization` header. Clients built on the\nnative browser `EventSource` cannot send headers; those can send the JWT in\nthe deprecated `authorization` query param instead.

🛡️ Requires Capabilities: None

", "parameters": [ { "name": "authorization", "required": false, "in": "query", "deprecated": true, "description": "The JWT, for EventSource implementations that cannot send an Authorization header.", "schema": {} } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." } }, "tags": [ "Events" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/users/public": { "get": { "operationId": "PublicUserController_getPublicUsers", "summary": "Get a list of users for the login screen.", "description": "

🛡️ Requires Capabilities: None

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "tags": [ "Users (Public)" ] } }, "/api/v1/users/current": { "get": { "operationId": "UserController_getCurrentUser", "summary": "🛡️ Get the currently logged in user.", "description": "

🛡️ Requires Capabilities: CurrentUser.Read

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUserResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "UserController_updateCurrentUser", "summary": "🛡️ Update your own user.", "description": "

🛡️ Requires Capabilities: CurrentUser.Update

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/users/owner": { "get": { "operationId": "UserController_getOwner", "summary": "🛡️ Returns the server owner, if there is one.", "description": "

🛡️ Requires Capabilities: Users.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/users/active": { "get": { "operationId": "UserController_getActiveUsers", "summary": "🛡️ Get active Media Server users.", "description": "

🛡️ Requires Capabilities: Users.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/users": { "get": { "operationId": "UserController_getUsers", "summary": "🛡️ Get all users in this server.", "description": "

🛡️ Requires Capabilities: Users.Read

", "parameters": [ { "name": "roles", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "post": { "operationId": "UserController_createLocalUser", "summary": "🛡️ Create a new local Media Server user.", "description": "

🛡️ Requires Capabilities: Users.Create

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUser" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/users/{id}": { "get": { "operationId": "UserController_getUser", "summary": "🛡️ Get a specific user.", "description": "

🛡️ Requires Capabilities: Users.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "UserController_updateUser", "summary": "🛡️ Update a user.", "description": "

🛡️ Requires Capabilities: Users.Update

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Users" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/licensing/subscription": { "get": { "operationId": "LicensingController_getCurrentSubscription", "summary": "🛡️ Get the subscription tier.", "description": "

🛡️ Requires Capabilities: Users.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Licensing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/licensing/seats": { "get": { "operationId": "LicensingController_getSeats", "summary": "🛡️ Get information about seat usage.", "description": "

🛡️ Requires Capabilities: Users.Read

", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Licensing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/roles/assignments": { "get": { "operationId": "RBACController_getRoleAssignments", "summary": "🛡️ Get role assignments.", "description": "Get all role assignments for all users, or all role assignments for just one user.

🛡️ Requires Capabilities: RoleAssignments.Read

", "parameters": [ { "name": "userId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "name", "enum": [ "name" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Role Assignments" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/roles/{role}/assignments": { "post": { "operationId": "RBACController_assignRoles", "summary": "🛡️ Assign roles.", "description": "Assign a role to one or more users by creating role assignments. If the user already has the role, the existing assignment will be returned.

🛡️ Requires Capabilities: RoleAssignments.Create

", "parameters": [ { "name": "role", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignRolesDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The role is non-assignable." } }, "tags": [ "Role Assignments" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "RBACController_revokeRoles", "summary": "🛡️ Revoke roles.", "description": "Revoke a role from one or more users by deleting role assignments. If the user does not have the role, nothing will happen. The Guest Account is protected from having its roles removed.

🛡️ Requires Capabilities: RoleAssignments.Delete

", "parameters": [ { "name": "userIds", "required": true, "in": "query", "schema": { "default": [], "type": "array", "items": { "type": "string" } } }, { "name": "role", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; You are attempting to update the Guest Account." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Role Assignments" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/state": { "get": { "operationId": "IndexingController_getState", "summary": "🛡️ Get the current state of the indexing service.", "description": "\nReturns a snapshot of the indexing state at \nthis current moment. Use this endpoint for one-time checks. \nFor real-time updates, use the `/events/subscribe` endpoint \ninstead.\n\n

🛡️ Requires Capabilities: Indexing.Read

", "parameters": [], "responses": { "200": { "description": "\nThe returned object will contain the state of the indexing service. \nPossible states are: `idle` `indexing` `paused`\n\n", "content": { "application/json": { "schema": { "example": { "state": "idle" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "IndexingController_changeState", "summary": "🛡️ Control the current indexing run.", "description": "\nUpdate the state of the currently running indexing operation. This endpoint\nis dedicated to controlling the indexing service from the frontend, and\ncannot update completed runs.\n\nThis endpoint is designed to accept actions. Instead of sending the desired\nstate, send an action and let the indexing service handle the change\ninternally. So, you send \"stop\", and internally the service will terminate\nthe run and change the state to `idle`.\n\nAccepted actions are:\n\n- `pause` - Pauses the run after the current file has completed indexing.\nThe internal state will change to `paused`.\n- `resume` - Resumes a run and continues with the next file. Triggering\nresume on a run that isn't paused will have no effect. The internal\nstate will change to `indexing`.\n- `stop` - Stops a run after the current file has completed indexing. The\ninternal state will change to `idle`, and a new run can be started.\n\n

🛡️ Requires Capabilities: Indexing.Operate

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateChangeActionDto" } } } }, "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." }, "409": { "description": "\nReturns a 409 if the action is not compatible \nwith the current indexing state. For example, sending `stop` \nwhile the server is `idle`.\n\n" } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/directories": { "get": { "operationId": "IndexingController_getDirectories", "summary": "🛡️ Get your media directories.", "description": "Returns an array of all media directories that the user told Cardinal Media Server to use.

🛡️ Requires Capabilities: Indexing.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/counts": { "get": { "operationId": "IndexingController_getFileCounts", "summary": "🛡️ Count your files.", "description": "

🛡️ Requires Capabilities: Indexing.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "example": { "musicFiles": 10, "photoFiles": 12, "movieFiles": 20, "tvFiles": 24 } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/run/logs": { "get": { "operationId": "IndexingController_getRunLogs", "summary": "🛡️ Get logs for an indexing run.", "description": "

🛡️ Requires Capabilities: Indexing.Read

", "parameters": [ { "name": "runId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/runs": { "get": { "operationId": "IndexingController_getRuns", "summary": "🛡️ Get your previous indexing runs.", "description": "

🛡️ Requires Capabilities: Indexing.Read

", "parameters": [ { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "example": [ [ { "runId": "7b74fae5-c377-4352-983d-0981e9b9fbec" } ], 24 ] } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/run": { "post": { "operationId": "IndexingController_startManualIndexingRun", "summary": "🛡️ Start an indexing run.", "description": "\nCreates a new Run in the database and starts the indexing operation for\nthat Run. This endpoint can only be used if there is not currently a run\nrunning.\n\nThe indexing operation will continue to run on the server after this\nendpoint has returned a response.\n\n

🛡️ Requires Capabilities: Indexing.Operate

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRunDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/file": { "get": { "operationId": "IndexingController_getFile", "summary": "🛡️ Get files from your index.", "description": "\nGet one or more files from your index. Depending on the filetype, addtional\ninformation will be returned about the entities that were extracted from\nthe file.\n\n

🛡️ Requires Capabilities: Indexing.Operate

", "parameters": [ { "name": "ids", "required": false, "in": "query", "schema": { "default": [], "type": "array", "items": { "type": "string" } } }, { "name": "library", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/files": { "delete": { "operationId": "IndexingController_deleteFiles", "summary": "🛡️ Deindex one or more of your files.", "description": "\nDeindexes one or more files. To \"deindex\" means to delete the file entity\nand all of its derived entities like songs and episodes, and all of their\nderived entities like metadata and thumbnails.\n\nDeindexing however does not delete cached static resources on the disk like\nthe thumbnail files that the server generates when initially indexing\nthings. Those now stale assets will eventually be deleted by a cleanup cron\njob.\n\nIf a wildcard (`*`) is given as the sole item in the array, all files will\nbe deindexed. The wildcard method only supports hard deleting, so you must\nalso set `hardDelete` to true to activate it. Only a `true` boolean will be\nreturned when the wildcard operation is done.\n\nBy default, this deindexing is a soft delete. To perform a hard delete, set\nthe `hardDelete` param to true.\n\n

🛡️ Requires Capabilities: Indexing.Deindex

", "parameters": [ { "name": "ids", "required": true, "in": "query", "schema": { "default": [], "type": "array", "items": { "type": "string" } } }, { "name": "hardDelete", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Returns an object of file IDs and booleans, indicating whether each file was successfully deindexed.", "content": { "application/json": { "schema": { "example": { "7b74fae5-c377-4352-983d-0981e9b9fbec": true } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/seed/large": { "post": { "operationId": "IndexingController_seedIndexLarge", "summary": "🛡️ Seed the index with millions of mock music files.", "description": "

🛡️ Requires Capabilities: Indexing.Operate

", "parameters": [ { "name": "count", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/seed/fs": { "post": { "operationId": "IndexingController_seedIndexFs", "summary": "🛡️ Seed the file system with mock music folders and files.", "description": "

🛡️ Requires Capabilities: Indexing.Operate

", "parameters": [ { "name": "artists", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/index/seed/demo": { "post": { "operationId": "IndexingController_seedIndexDemo", "summary": "🛡️ Seed the curated public demo dataset (kiosk mode only).", "description": "

🛡️ Requires Capabilities: Indexing.Operate

", "parameters": [ { "name": "username", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "scale", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Indexing" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/track/{id}": { "get": { "operationId": "MusicTrackController_getMusicTrack", "summary": "🛡️ Get a single music track.", "description": "

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicTrackComputed" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/tracks": { "get": { "operationId": "MusicTrackController_getTracks", "summary": "🛡️ Query music tracks.", "description": "

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Only tracks whose title contains this text. Case-insensitive, matches anywhere in the text, and `%` and `_` are literal. Surrounding whitespace is trimmed, and a blank term applies no filter.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "release", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "artists", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "libraries", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "playCount", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "rating", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "releasedSince", "required": false, "in": "query", "schema": { "pattern": "/^\\d{4}-\\d{2}-\\d{2}$/", "type": "string" } }, { "name": "favorites", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "hot", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "orderBy", "required": false, "in": "query", "schema": { "default": "title", "enum": [ "createdAt", "title", "trackNumber", "discNumber", "duration", "bitrate", "playCount", "rating", "favoritedAt", "hotPlays" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/stream/{id}": { "get": { "operationId": "MusicTrackController_streamMusicTrack", "summary": "🛡️ Stream a music track.", "description": "Stream a music track using either direct stream or transcoding.

🛡️ Requires Capabilities: MusicTracks.Play

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "transcode", "required": false, "in": "query", "description": "Transcode to MP3 on the fly. A bare `?transcode` turns it on, as do `true` and `1`; `false` and `0` turn it off. MP3 sources are always streamed directly.", "schema": { "default": false, "type": "boolean" } }, { "name": "bitrate", "required": false, "in": "query", "description": "Transcoding bitrate in kbps. Encoded at the nearest standard MP3 bitrate.", "schema": { "minimum": 32, "maximum": 320, "default": 320, "type": "integer" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT (Query Parameter)": [] }, { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/library": { "post": { "operationId": "LibraryController_createLibrary", "summary": "🛡️ Create a new library.", "description": "

🛡️ Requires Capabilities: Libraries.Create

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLibraryDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Library" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Libraries" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/libraries": { "get": { "operationId": "LibraryController_getLibraries", "summary": "🛡️ Get the current user's all libraries.", "description": "

🛡️ Requires Capabilities: Libraries.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Library" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Libraries" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/library/{id}": { "get": { "operationId": "LibraryController_getLibrary", "summary": "🛡️ Get a library.", "description": "

🛡️ Requires Capabilities: Libraries.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Library" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Libraries" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "LibraryController_updateLibrary", "summary": "🛡️ Update a library.", "description": "

🛡️ Requires Capabilities: Libraries.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLibraryBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Library" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Libraries" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "LibraryController_deleteLibrary", "summary": "🛡️ Delete a library.", "description": "

🛡️ Requires Capabilities: Libraries.Delete

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Libraries" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/release/{id}": { "get": { "operationId": "MusicReleaseController_getMusicArtist", "summary": "🛡️ Get a single music release.", "description": "

🛡️ Requires Capabilities: MusicReleases.Read

", "parameters": [ { "name": "tracks", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "genres", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "artists", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "thumbnails", "required": false, "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicRelease" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/releases": { "get": { "operationId": "MusicReleaseController_getMusicReleases", "summary": "🛡️ Query music releases.", "description": "

🛡️ Requires Capabilities: MusicReleases.Read

", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Only releases whose title contains this text. Case-insensitive, matches anywhere in the text, and `%` and `_` are literal. Surrounding whitespace is trimmed, and a blank term applies no filter.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "genres", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "tracks", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "artists", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "thumbnails", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "libraries", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "favorites", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "orderBy", "required": false, "in": "query", "schema": { "default": "title", "enum": [ "createdAt", "title", "favoritedAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/releases/{id}/cover": { "get": { "operationId": "MusicReleaseController_getReleaseCoverBlob", "summary": "🛡️ Get the cover image of a release.", "description": "

🛡️ Requires Capabilities: MusicReleases.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The release to address, given as either its numeric row ID or its UUID release ID.", "schema": { "type": "string" } }, { "name": "size", "required": false, "in": "query", "schema": { "default": "small_nocrop", "enum": [ "small_nocrop", "medium_nocrop" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/artist/{id}": { "get": { "operationId": "MusicArtistController_getMusicArtist", "summary": "🛡️ Get a single music artist.", "description": "

🛡️ Requires Capabilities: MusicArtists.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "releases", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "tracks", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "summary", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "playCount", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "rating", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/artists": { "get": { "operationId": "MusicArtistController_getMusicArtists", "summary": "🛡️ Query music artists.", "description": "

🛡️ Requires Capabilities: MusicArtists.Read

", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Only artists whose name contains this text. Case-insensitive, matches anywhere in the text, and `%` and `_` are literal. Surrounding whitespace is trimmed, and a blank term applies no filter.", "schema": { "maxLength": 200, "type": "string" } }, { "name": "tracks", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "releases", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "libraries", "required": false, "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "orderBy", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt", "updatedAt", "name", "sortName" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/ratings": { "put": { "operationId": "RatingController_setRating", "summary": "🛡️ Set a rating for a media item.", "description": "

🛡️ Requires Capabilities: Ratings.Create

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRatingDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rating" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Ratings" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "get": { "operationId": "RatingController_queryRatings", "summary": "🛡️ Query ratings for the currently logged in user.", "description": "

🛡️ Requires Capabilities: Ratings.Read

", "parameters": [ { "name": "favorites", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "music_track" ], "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt", "rating" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Ratings" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/ratings/{mediaType}/{mediaId}": { "delete": { "operationId": "RatingController_deleteRating", "summary": "🛡️ Remove a rating for a media item.", "description": "

🛡️ Requires Capabilities: Ratings.Delete

", "parameters": [ { "name": "mediaType", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "mediaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Ratings" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/genre/{id}": { "get": { "operationId": "MusicGenreController_getMusicArtist", "summary": "🛡️ Get a single music genre.", "description": "

🛡️ Requires Capabilities: MusicGenres.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicGenre" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photos": { "get": { "operationId": "PhotoController_getPhotos", "summary": "🛡️ Get your photos.", "description": "

🛡️ Requires Capabilities: Photos.Read

", "parameters": [ { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "thumbnails", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "photoAlbumEntries", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "orderBy", "required": false, "in": "query", "schema": { "default": "takenAt", "enum": [ "createdAt", "takenAt", "modifiedAt", "width", "height", "deviceMake", "deviceModel", "gpsLat", "gpsLng", "gpsAltitude" ], "type": "string" } }, { "name": "order", "required": false, "in": "query", "schema": { "default": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } } ], "responses": { "200": { "description": "Returns an array where the first item is an array of query results, and the second item is the total number of photos.", "content": { "application/json": { "schema": { "example": [ [ { "photoId": "7b74fae5-c377-4352-983d-0981e9b9fbec" }, { "photoId": "7b74fae5-c377-4352-983d-0981e9b9fbec" }, { "photoId": "7b74fae5-c377-4352-983d-0981e9b9fbec" }, { "photoId": "7b74fae5-c377-4352-983d-0981e9b9fbec" } ], 24 ] } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photos/coordinates": { "get": { "operationId": "PhotoController_getPhotoCoordinates", "summary": "🛡️ Get the coordinates of every geotagged photo.", "description": "Photos that carry no coordinates are omitted, and no relations are joined, so a whole library fits in one response.

🛡️ Requires Capabilities: Photos.Read

", "parameters": [], "responses": { "200": { "description": "Returns an array of `[id, photoId, latitude, longitude]` tuples, ordered by row ID.", "content": { "application/json": { "schema": { "example": [ [ 1, "7b74fae5-c377-4352-983d-0981e9b9fbec", 40.741895, -73.989308 ], [ 2, "b0a1cdd3-1e2b-4b8a-9a7d-0f2f9b2a1c44", 51.500729, -0.124625 ] ] } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photos/count": { "get": { "operationId": "PhotoController_countPhotos", "summary": "🛡️ Count your photos.", "description": "

🛡️ Requires Capabilities: Photos.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "number" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo/{id}": { "get": { "operationId": "PhotoController_getPhoto", "summary": "🛡️ Get data about a photo.", "description": "

🛡️ Requires Capabilities: Photos.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo to address, given as either its numeric row ID or its UUID photo ID.", "schema": { "type": "string" } }, { "name": "file", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "thumbnails", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "photoAlbumEntries", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "PhotoController_updatePhoto", "summary": "🛡️ Update a photo.", "description": "

🛡️ Requires Capabilities: Photos.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo to address, given as either its numeric row ID or its UUID photo ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhotoBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Photo" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo/{id}/blob": { "get": { "operationId": "PhotoController_getPhotoBlob", "summary": "🛡️ Get a photo blob.", "description": "

🛡️ Requires Capabilities: Photos.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo to address, given as either its numeric row ID or its UUID photo ID.", "schema": { "type": "string" } }, { "name": "autoConvert", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo/{id}/thumbnail": { "get": { "operationId": "PhotoController_getReleaseCoverBlob", "summary": "🛡️ Get a photo thumbnail.", "description": "

🛡️ Requires Capabilities: Photos.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo to address, given as either its numeric row ID or its UUID photo ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photos" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo-album/{id}": { "get": { "operationId": "PhotoAlbumController_getPhotoAlbum", "summary": "🛡️ Get a single photo album.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoAlbumComputed" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "PhotoAlbumController_updatePhotoAlbum", "summary": "🛡️ Update a photo album.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhotoAlbumBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoAlbum" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "PhotoAlbumController_deletePhotoAlbum", "summary": "🛡️ Delete a photo album.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Delete

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo-albums": { "get": { "operationId": "PhotoAlbumController_getPhotoAlbums", "summary": "🛡️ Get your photo albums.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Read

", "parameters": [ { "name": "metadata", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "thumbnails", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "orderBy", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt", "modifiedAt", "takenAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo-albums/count": { "get": { "operationId": "PhotoAlbumController_countPhotoAlbums", "summary": "🛡️ Count your photo albums.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "number" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo-album": { "post": { "operationId": "PhotoAlbumController_createPhotoAlbum", "summary": "🛡️ Create a new photo album.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Create

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhotoAlbumDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoAlbum" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo-album/{id}/entries": { "get": { "operationId": "PhotoAlbumController_getPhotoAlbumEntries", "summary": "🛡️ Get photo album entries.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } }, { "name": "joinPhoto", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "joinPhotoAlbum", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "featured", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "orderBy", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt", "modifiedAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "post": { "operationId": "PhotoAlbumController_addPhotoAlbumEntries", "summary": "🛡️ Add photos to a photo album.", "description": "Photos already in the album, and photo IDs that address nothing, are reported as skipped rather than rejected.

🛡️ Requires Capabilities: PhotoAlbums.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoAlbumEntriesBodyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "PhotoAlbumController_removePhotoAlbumEntries", "summary": "🛡️ Remove photos from a photo album.", "description": "Photos that are not in the album are ignored. Removing the featured photo promotes another of the album's photos in its place.

🛡️ Requires Capabilities: PhotoAlbums.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoAlbumEntriesBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/photo-album/{id}/featured": { "put": { "operationId": "PhotoAlbumController_setFeaturedPhoto", "summary": "🛡️ Set the featured photo of a photo album.", "description": "

🛡️ Requires Capabilities: PhotoAlbums.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The photo album to address, given as either its numeric row ID or its UUID album ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFeaturedPhotoBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoAlbumEntry" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Photo Albums" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/thumbnails": { "delete": { "operationId": "ThumbnailController_deleteThumbnailFileCache", "summary": "🛡️ Delete all cached thumbnails files.", "description": "

🛡️ Requires Capabilities: Indexing.Deindex

", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Thumbnails" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/job": { "post": { "operationId": "JobController_createJob", "summary": "🛡️ Create a new job.", "description": "The job will automatically start running.

🛡️ Requires Capabilities: Jobs.Create

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Jobs" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/jobs": { "get": { "operationId": "JobController_getJobs", "summary": "🛡️ Fetch server jobs.", "description": "

🛡️ Requires Capabilities: Jobs.Read

", "parameters": [ { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "status", "required": true, "in": "query", "description": "draft, preparing, in_queue, running, paused, canceled, completed, errored", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "type", "required": true, "in": "query", "description": "album_art_thumbnails, photo_variations, photo_thumbnails, generate_waveforms, cloud_backup, cloud_restore", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Jobs" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/job/{id}": { "get": { "operationId": "JobController_getJob", "summary": "🛡️ Get a single job.", "description": "

🛡️ Requires Capabilities: Jobs.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job to address, given as either its numeric row ID or its UUID job ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Jobs" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "JobController_updateJob", "summary": "🛡️ Control a job.", "description": "Control a job by updating its status. Pausing will only kick in between the next job tasks, resuming is instant.

🛡️ Requires Capabilities: Jobs.Operate

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job to address, given as either its numeric row ID or its UUID job ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Jobs" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/job/{id}/tasks": { "get": { "operationId": "JobController_getJobTasks", "summary": "🛡️ Get a job's tasks.", "description": "

🛡️ Requires Capabilities: Jobs.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The job to address, given as either its numeric row ID or its UUID job ID.", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "create_album_artwork_thumbnail", "create_photo_thumbnail", "heic_to_jpeg", "generate_track_waveform", "upload_file", "restore_file" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Jobs" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/jobs/types": { "get": { "operationId": "JobController_getJobTypes", "summary": "🛡️ Get all job types.", "description": "

🛡️ Requires Capabilities: Jobs.Read

", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Jobs" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/track/{id}/waveform": { "get": { "operationId": "WaveformController_getMusicTrackWaveform", "summary": "🛡️ Get the waveform of a music track.", "description": "Returns the stored waveform data for a track. When no current waveform exists yet, responds with 202 and begins generating one; a `music.waveform_ready` server-sent event announces the result.

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicTrackWaveform" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups": { "post": { "operationId": "BackupController_createBackupConfig", "summary": "🛡️ Set up a backup.", "description": "Issues this server's backup credential from Cardinal Cloud, registers the backup, and saves its schedule. Requires the cloud account JWT header. An encrypted backup returns its recovery kit in the response, which is the only time it can be read.

🛡️ Requires Capabilities: Backups.Create

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBackupConfigDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The cloud account JWT header is missing; An encrypted backup was requested without a passphrase." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The cloud account has no approved access to backups, and the request has been queued (code service_access_required)." }, "409": { "description": "This server already has an encrypted backup, or the backup service refused the call (a suspended account, for example)." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "get": { "operationId": "BackupController_getBackupConfigs", "summary": "🛡️ Get this server's backups.", "description": "

🛡️ Requires Capabilities: Backups.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BackupConfig" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups/{id}": { "get": { "operationId": "BackupController_getBackupConfig", "summary": "🛡️ Get a backup.", "description": "

🛡️ Requires Capabilities: Backups.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupConfig" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "patch": { "operationId": "BackupController_updateBackupConfig", "summary": "🛡️ Update a backup.", "description": "Changes the schedule, the libraries, the sections, or whether the backup is enabled. The storage class and the encryption choice are fixed when the backup is created.

🛡️ Requires Capabilities: Backups.Update

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBackupConfigDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupConfig" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The payload changes the storage class or the encryption choice; A time of day was set on an hourly schedule." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "BackupController_deleteBackupConfig", "summary": "🛡️ Delete a backup.", "description": "Deletes the backup here and flags its stored data for removal by the backup service.

🛡️ Requires Capabilities: Backups.Delete

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups/{id}/reset": { "post": { "operationId": "BackupController_resetBackup", "summary": "🛡️ Reset a backup.", "description": "Returns this server to never having had a backup. The backup service is asked to release the stored data first, and only once it agrees is the local configuration — the schedule, the sections and the key to an encrypted backup — deleted. A backup that has stored something answers with the date its data is scheduled to be removed; one that never finished a run is removed outright and answers with no date.

🛡️ Requires Capabilities: Backups.Delete

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The cloud account has no approved access to backups, and the request has been queued (code service_access_required)." }, "409": { "description": "The backup service refused to release the stored data (a suspended account, for example)." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups/{id}/status": { "get": { "operationId": "BackupController_getStatus", "summary": "🛡️ Get a backup's status.", "description": "

🛡️ Requires Capabilities: Backups.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups/{id}/snapshots": { "get": { "operationId": "BackupController_listSnapshots", "summary": "🛡️ List a backup's snapshots.", "description": "Answers from the backup service are passed through untouched, including its refusals. The service pages its snapshots and this returns its first page.

🛡️ Requires Capabilities: Backups.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups/{id}/run": { "post": { "operationId": "BackupController_triggerBackup", "summary": "🛡️ Back up now.", "description": "Queues a backup run. Refuses while a run of this backup is already queued or in progress.

🛡️ Requires Capabilities: Backups.Operate

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." }, "409": { "description": "A run of this backup is already queued or in progress." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/backups/{id}/restore": { "post": { "operationId": "BackupController_triggerRestore", "summary": "🛡️ Restore a snapshot.", "description": "Queues a restore of one snapshot. A passphrase is only needed when this server holds no key for an encrypted backup; it is handed to the restore in memory and never stored.

🛡️ Requires Capabilities: Backups.Operate

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerRestoreDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." }, "409": { "description": "A run of this backup is already queued or in progress." } }, "tags": [ "Backups" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/history": { "patch": { "operationId": "MusicHistoryController_createPlaybackHistoryEntry", "summary": "🛡️ Save playback history.", "description": "

🛡️ Requires Capabilities: MusicHistory.Create

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMusicHistoryEntryDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicHistory" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "get": { "operationId": "MusicHistoryController_queryPlaybackHistory", "summary": "🛡️ Query playback history for the currently logged in user.", "description": "

🛡️ Requires Capabilities: MusicHistory.Read

", "parameters": [ { "name": "sort", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/notifications": { "get": { "operationId": "NotificationController_queryNotifications", "summary": "🛡️ Query notifications for the currently logged in user.", "description": "

🛡️ Requires Capabilities: Notifications.Read

", "parameters": [ { "name": "unreadOnly", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt", "readAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Notifications" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/notifications/read-all": { "post": { "operationId": "NotificationController_markAllRead", "summary": "🛡️ Mark all of the current user's notifications read.", "description": "

🛡️ Requires Capabilities: Notifications.Update

", "parameters": [], "responses": { "201": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Notifications" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/notifications/{notificationId}": { "patch": { "operationId": "NotificationController_updateNotification", "summary": "🛡️ Mark a notification read or unread.", "description": "

🛡️ Requires Capabilities: Notifications.Update

", "parameters": [ { "name": "notificationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Notifications" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/users/{id}/personal-access-tokens": { "get": { "operationId": "PersonalAccessTokenController_listTokens", "summary": "🛡️ List a user's personal access tokens.", "description": "Token secrets are shown once, when the token is created, and are never returned again.

🛡️ Requires Capabilities: PersonalAccessTokens.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The request used a personal access token, and this endpoint requires an interactive session." } }, "tags": [ "Personal Access Tokens" ], "security": [ { "Local User JWT": [] } ] }, "post": { "operationId": "PersonalAccessTokenController_createToken", "summary": "🛡️ Create a personal access token for a user.", "description": "The response carries the token secret. It is not stored and cannot be shown again.

🛡️ Requires Capabilities: PersonalAccessTokens.Create

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePersonalAccessTokenDto" } } } }, "responses": { "201": { "description": "" }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The expiry is not a valid ISO 8601 date." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The request used a personal access token, and this endpoint requires an interactive session." } }, "tags": [ "Personal Access Tokens" ], "security": [ { "Local User JWT": [] } ] } }, "/api/v1/users/{id}/personal-access-tokens/{tokenId}": { "delete": { "operationId": "PersonalAccessTokenController_revokeToken", "summary": "🛡️ Revoke a personal access token.", "description": "

🛡️ Requires Capabilities: PersonalAccessTokens.Delete

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "tokenId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The request used a personal access token, and this endpoint requires an interactive session." } }, "tags": [ "Personal Access Tokens" ], "security": [ { "Local User JWT": [] } ] } }, "/api/v1/playback-queues/{id}": { "get": { "operationId": "PlaybackQueueController_getPlaybackQueue", "summary": "🛡️ Get a queue.", "description": "

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackQueue" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "PlaybackQueueController_deletePlaybackQueue", "summary": "🛡️ Delete a queue.", "description": "

🛡️ Requires Capabilities: MusicTracks.Play

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "boolean" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/playback-queues": { "get": { "operationId": "PlaybackQueueController_queryPlaybackQueues", "summary": "🛡️ Query queues.", "description": "

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "static", "dynamic" ], "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "post": { "operationId": "PlaybackQueueController_createPlaybackQueue", "summary": "🛡️ Create a new queue.", "description": "

🛡️ Requires Capabilities: MusicTracks.Play

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlaybackQueueDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackQueue" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/playback-queues/{id}/items": { "get": { "operationId": "PlaybackQueueController_queryPlaybackQueueItems", "summary": "🛡️ Query queue items.", "description": "

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "currentQueueItemId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "leading", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "trailing", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "includeCurrentItemInReturn", "required": false, "in": "query", "schema": { "default": true, "type": "boolean" } }, { "name": "sort", "required": false, "in": "query", "schema": { "default": "createdAt", "enum": [ "createdAt" ], "type": "string" } }, { "name": "take", "required": false, "in": "query", "schema": { "default": 12, "type": "number" } }, { "name": "skip", "required": false, "in": "query", "schema": { "default": 0, "type": "number" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/playback-queues/{id}/items/{queueItemId}": { "patch": { "operationId": "PlaybackQueueController_movePlaybackQueueItem", "summary": "🛡️ Move a queue item behind another one.", "description": "

🛡️ Requires Capabilities: MusicTracks.Play

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "queueItemId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovePlaybackQueueItemDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackQueueItem" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/playback-queues/{id}/extend": { "post": { "operationId": "PlaybackQueueController_extend", "summary": "🛡️ Add items to a queue.", "description": "

🛡️ Requires Capabilities: MusicTracks.Play

", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendPlaybackQueueDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackQueueItem" } } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Playback Queues" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/popularity/stats": { "get": { "operationId": "PopularityController_getStats", "summary": "🛡️ Get this server's Popularity Data Pool contribution stats.", "description": "

🛡️ Requires Capabilities: ServerSettings.Read

", "parameters": [], "responses": { "200": { "description": "" }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Popularity" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/spotlight/artist": { "get": { "operationId": "RecommendationController_getArtistSpotlight", "summary": "🛡️ Get the artist spotlight for the current user: a personal artist pick with the reason it was picked.", "description": "

🛡️ Requires Capabilities: MusicArtists.Read

", "parameters": [ { "name": "position", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/spotlight/release": { "get": { "operationId": "RecommendationController_getReleaseSpotlight", "summary": "🛡️ Get the release spotlight for the current user: a personal release pick with the reason it was picked.", "description": "

🛡️ Requires Capabilities: MusicReleases.Read

", "parameters": [ { "name": "position", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/music/spotlight/track": { "get": { "operationId": "RecommendationController_getTrackSpotlight", "summary": "🛡️ Get the track spotlight for the current user: a personal track pick with the reason it was picked.", "description": "

🛡️ Requires Capabilities: MusicTracks.Read

", "parameters": [ { "name": "position", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Music" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/telemetry": { "post": { "operationId": "TelemetryController_ingest", "summary": "Submit telemetry events.", "description": "Accepted and forwarded only while the server-wide telemetry setting is on, otherwise discarded. Always answers 202.

🛡️ Requires Capabilities: None

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestTelemetryEventsDto" } } } }, "responses": { "202": { "description": "The events were accepted for forwarding." }, "401": { "description": "Possible reasons: The authorization token is invalid." } }, "tags": [ "Telemetry" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/port-mapper/status": { "get": { "operationId": "PortMapperController_getStatus", "summary": "🛡️ Get the UPnP port mapping status.", "description": "

🛡️ Requires Capabilities: ServerSettings.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortMapperStatusResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/port-mapper/settings": { "put": { "operationId": "PortMapperController_updateSettings", "summary": "🛡️ Update the UPnP port mapping setting.", "description": "Enables or disables automatic port forwarding. Enabling maps the port immediately when the Remote Access listener is already running.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePortMapperSettingsDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortMapperStatusResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/connect/enable": { "post": { "operationId": "ConnectSDKController_enable", "summary": "🛡️ Enable Remote Access.", "description": "Issues a Remote Access credential from Cardinal Cloud for this server and opens the control channel. Requires the cloud account JWT header.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectStatusResponse" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectStatusResponse" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The cloud account JWT header is missing." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The cloud account has no approved access to Remote Access, and the request has been queued (code service_access_required)." }, "409": { "description": "The cloud IDP refused: every server slot on the cloud account is occupied." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/connect/disable": { "post": { "operationId": "ConnectSDKController_disable", "summary": "🛡️ Disable Remote Access.", "description": "Closes the control channel and disables Remote Access. When the cloud account JWT header is present, the Remote Access credential is also revoked with Cardinal Cloud.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectStatusResponse" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectStatusResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/connect/status": { "get": { "operationId": "ConnectSDKController_status", "summary": "🛡️ Get the Remote Access status.", "description": "

🛡️ Requires Capabilities: ServerSettings.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectStatusResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/connect/vanity/availability": { "get": { "operationId": "ConnectSDKController_vanityAvailability", "summary": "🛡️ Check whether a vanity hostname is available.", "description": "Answers from the Remote Access Server are passed through untouched, including its refusals: 422 invalid_name, 409 name_unavailable / label_limit_reached, 429 rename_cooldown, 402 cert_unavailable and 503 vanity_disabled.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "name", "required": true, "in": "query", "description": "The vanity label, without any domain suffix.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VanityAvailabilityResponse" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; Remote Access is not enabled on this server, or it holds no cloud credential." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/connect/vanity": { "get": { "operationId": "ConnectSDKController_vanity", "summary": "🛡️ Get this server's vanity hostnames.", "description": "Answers from the Remote Access Server are passed through untouched, including its refusals: 422 invalid_name, 409 name_unavailable / label_limit_reached, 429 rename_cooldown, 402 cert_unavailable and 503 vanity_disabled.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VanityStatusResponse" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; Remote Access is not enabled on this server, or it holds no cloud credential." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "put": { "operationId": "ConnectSDKController_setVanity", "summary": "🛡️ Claim a vanity hostname for this server.", "description": "Answers from the Remote Access Server are passed through untouched, including its refusals: 422 invalid_name, 409 name_unavailable / label_limit_reached, 429 rename_cooldown, 402 cert_unavailable and 503 vanity_disabled.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetVanityNameDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VanityStatusResponse" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; Remote Access is not enabled on this server, or it holds no cloud credential." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] }, "delete": { "operationId": "ConnectSDKController_releaseVanity", "summary": "🛡️ Release one of this server's vanity hostnames.", "description": "Answers from the Remote Access Server are passed through untouched, including its refusals: 422 invalid_name, 409 name_unavailable / label_limit_reached, 429 rename_cooldown, 402 cert_unavailable and 503 vanity_disabled.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "name", "required": true, "in": "query", "description": "The vanity label, without any domain suffix.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VanityStatusResponse" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; Remote Access is not enabled on this server, or it holds no cloud credential." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Remote Access" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/uptime/enable": { "post": { "operationId": "UptimeController_enable", "summary": "🛡️ Turn Uptime on.", "description": "Issues an Uptime credential from Cardinal Cloud for this server and starts checking in. Requires the cloud account JWT header.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeStatusResponse" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeStatusResponse" } } } }, "400": { "description": "Possible reasons: Request validation failed, see response for details; The cloud account JWT header is missing." }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities; The cloud account may not use Uptime." } }, "tags": [ "Uptime" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/uptime/disable": { "post": { "operationId": "UptimeController_disable", "summary": "🛡️ Turn Uptime off.", "description": "Stops checking in and tells Cardinal Cloud that the silence is deliberate, so it is not reported as an outage. When the cloud account JWT header is present, the Uptime credential is also revoked with Cardinal Cloud.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [ { "name": "CardinalTolkien", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeDisableResponse" } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeDisableResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Uptime" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/uptime/check-in": { "post": { "operationId": "UptimeController_checkIn", "summary": "🛡️ Check in now.", "description": "Sends one check-in to Cardinal Cloud immediately and answers with the status it left behind. The scheduled check-ins carry on unchanged. A check-in already in flight is not duplicated; the status still comes back.

🛡️ Requires Capabilities: ServerSettings.Update

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeStatusResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." }, "409": { "description": "Possible reasons: Uptime is not turned on for this server, or this server holds no Uptime credential to check in with." } }, "tags": [ "Uptime" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } }, "/api/v1/uptime/status": { "get": { "operationId": "UptimeController_status", "summary": "🛡️ Get the Uptime status.", "description": "

🛡️ Requires Capabilities: ServerSettings.Read

", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UptimeStatusResponse" } } } }, "401": { "description": "Possible reasons: The authorization token is invalid." }, "403": { "description": "Possible reasons: The user does not have sufficent capabilities." } }, "tags": [ "Uptime" ], "security": [ { "Local User JWT": [] }, { "Personal Access Token": [] } ] } } }, "info": { "title": "Cardinal Media Server API", "description": "

This is the API specification for your Cardinal Media Server.

\n

For the responsible disclosure of a security vulnerability, please email hackers@cardinalapps.io.

\n

Authorization

\n

There are two authorization tokens, and both are stored in your browser after you log in. You can enable developer mode in the app settings and copy the tokens from there.

\n
    \n
  • @cardinal/media_server_user_tolkien: Token for an account in your Media Server.
    • \n
  • @cardinal/cloud_user_tolkien: Token for a Cardinal cloud account. Some endpoints require this in addition to the other token.
    • \n
\n

Use the media_server_user_tolkien as the main authorization token in this API. Use the cloud_user_tolkien for endpoints that require the CardinalTolkien parameter or header.

\n

Some endpoints (e.g. audio streaming) accept the local user JWT as a token query parameter instead of the Authorization header, for contexts where custom request headers cannot be set (such as the browser's native <audio> element). The query parameter takes lower priority than the header; use the header wherever possible.

\n

Deleting Things

\n

None of the deletion endpoints in this API will delete your source media files. The only files that Cardinal will delete are the ones from its own cache. Rest assured that you can delete things from your database and your original files will stay safe.

\n ", "version": "", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "Local User JWT": { "scheme": "Bearer", "bearerFormat": "JWT", "name": "Authorization", "description": "Enter the JWT generated by your Cardinal Media Server for a local user. Do not prefix with \"Bearer\".", "type": "http", "in": "Header" }, "Local User JWT (Query Parameter)": { "type": "apiKey", "in": "query", "name": "token", "description": "Alternative to the Authorization header for contexts where custom headers cannot be set (e.g. browser native audio/video elements). Pass the local user JWT as the `token` query parameter. Use the Authorization header instead whenever possible." }, "Personal Access Token": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "A personal access token, for clients that cannot hold an interactive session. Pass the whole secret, starting with `cardinal_pat_`, as the Authorization header. Most endpoints accept one; those that manage tokens themselves do not." } }, "schemas": { "ServerSetupDto": { "type": "object", "properties": { "theme": { "type": "string" }, "serverName": { "type": "string" }, "sendAnonymousUsageData": { "type": "boolean" }, "ssoToken": { "type": "string" } } }, "ServerResetDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "media", "factory" ] }, "validationString": { "type": "string", "enum": [ "Deindex media", "Factory reset" ] } }, "required": [ "type", "validationString" ] }, "LoginDetails": { "type": "object", "properties": { "userId": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "cardinalJWT": { "type": "string" } } }, "LoginResponse": { "type": "object", "properties": { "JWT": { "type": "string" }, "user": { "type": "object" }, "cloudJWT": { "type": "string" }, "cloudUser": { "type": "object" }, "refreshToken": { "type": "string" }, "scope": { "type": "object" } }, "required": [ "JWT", "user" ] }, "CorsOrigin": { "type": "object", "properties": { "corsOriginId": { "type": "string" }, "origin": { "type": "string" }, "addedByUserId": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "corsOriginId", "origin", "id", "createdAt", "updatedAt", "deletedAt" ] }, "AddCorsOriginDto": { "type": "object", "properties": { "origin": { "type": "string", "description": "The origin to allow, as a well-formed http:// or https:// URL. Only the scheme, host, and port are kept.", "example": "https://birdhouse.example.com:8123" } }, "required": [ "origin" ] }, "CreateInvitationDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "administrator", "media_apps_user", "music_user", "photos_user", "cinema_user", "newcomer" ] }, "expiresAt": { "type": "string" }, "targetPublicUserId": { "type": "string" } }, "required": [ "role" ] }, "GetAppSettingsResponse": { "type": "object", "properties": { "settings": { "type": "object", "default": {} } }, "required": [ "settings" ] }, "UpsertSettings": { "type": "object", "properties": { "app": { "type": "string", "enum": [ "admin", "music", "photos", "cinema" ] }, "settings": { "type": "object", "default": {} } }, "required": [ "settings" ] }, "UpsertSettingsResponse": { "type": "object", "properties": { "updated": { "type": "object", "default": {} } } }, "GetUserResponse": { "type": "object", "properties": { "cardinalUser": { "type": "object" }, "localUser": { "type": "object" } }, "required": [ "localUser" ] }, "UpdateUserDto": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "password": { "type": "string" } } }, "User": { "type": "object", "properties": { "userId": { "type": "string" }, "cardinalId": { "type": "string" }, "cachedCloudUser": { "type": "object", "properties": { "subscription": { "required": true, "enum": [ "free", "early_adopter", "starter", "pro", "ultimate" ], "type": "string" } } }, "cachedCloudUserAt": { "format": "date-time", "type": "string" }, "enabled": { "type": "boolean" }, "role": { "type": "string" }, "designation": { "type": "string" }, "activityStatus": { "type": "string" }, "activityStatusUpdatedAt": { "format": "date-time", "type": "string" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RoleAssignment" } }, "username": { "type": "string" }, "password": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "userId", "cachedCloudUser", "role", "roles", "id", "createdAt", "updatedAt", "deletedAt" ] }, "RoleAssignment": { "type": "object", "properties": { "id": { "type": "number" }, "user": { "$ref": "#/components/schemas/User" }, "role": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "user", "role", "createdAt", "updatedAt", "deletedAt" ] }, "CreateUser": { "type": "object", "properties": { "cardinalJWT": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "role": { "type": "object" } }, "required": [ "role" ] }, "AssignRolesDto": { "type": "object", "properties": { "userIds": { "default": [], "type": "array", "items": { "type": "string" } } }, "required": [ "userIds" ] }, "StateChangeActionDto": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "stop" ] } }, "required": [ "action" ] }, "CreateRunDto": { "type": "object", "properties": { "indexMusic": { "type": "boolean" }, "indexPhotos": { "type": "boolean" }, "indexMovies": { "type": "boolean" }, "indexTV": { "type": "boolean" }, "type": { "type": "string", "enum": [ "quick", "full" ] } }, "required": [ "indexMusic", "indexPhotos", "indexMovies", "indexTV", "type" ] }, "Run": { "type": "object", "properties": { "runId": { "type": "string" }, "file": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "status": { "type": "string" }, "completedAt": { "format": "date-time", "type": "string" }, "type": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "runId", "status", "completedAt", "type", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicGenre": { "type": "object", "properties": { "releases": { "type": "array", "items": { "$ref": "#/components/schemas/MusicRelease" } }, "musicGenreId": { "type": "string" }, "name": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "musicGenreId", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicReleaseMetadata": { "type": "object", "properties": { "release": { "$ref": "#/components/schemas/MusicRelease" }, "metadataType": { "type": "object" }, "metadataFormat": { "type": "object" }, "metaKey": { "type": "string" }, "metaValue": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "release", "metaKey", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicReleaseThumbnail": { "type": "object", "properties": { "thumbnailId": { "type": "string" }, "absolutePath": { "type": "string", "nullable": true }, "relativeSrc": { "type": "string", "nullable": true }, "size": { "type": "string" }, "format": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" }, "release": { "$ref": "#/components/schemas/MusicRelease" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "thumbnailId", "absolutePath", "relativeSrc", "size", "format", "width", "height", "bytes", "release", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicRelease": { "type": "object", "properties": { "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/MusicTrack" } }, "artist": { "$ref": "#/components/schemas/MusicArtist" }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/MusicArtist" } }, "genres": { "type": "array", "items": { "$ref": "#/components/schemas/MusicGenre" } }, "musicReleaseId": { "type": "string" }, "title": { "type": "string" }, "sortTitle": { "type": "string" }, "releaseType": { "enum": [ "album", "ep", "single", "compilation", "soundtrack", "live", "remix", "dj-mix", "broadcast", "demo" ], "type": "string" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/MusicReleaseMetadata" } }, "thumbnails": { "type": "array", "items": { "$ref": "#/components/schemas/MusicReleaseThumbnail" } }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "musicReleaseId", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicArtistMetadata": { "type": "object", "properties": { "musicTrack": { "$ref": "#/components/schemas/MusicArtist" }, "metadataType": { "type": "object" }, "metadataFormat": { "type": "object" }, "metaKey": { "type": "string" }, "metaValue": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "musicTrack", "metaKey", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicArtist": { "type": "object", "properties": { "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/MusicTrack" } }, "releases": { "type": "array", "items": { "$ref": "#/components/schemas/MusicRelease" } }, "musicArtistId": { "type": "string" }, "name": { "type": "string" }, "sortName": { "type": "string" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/MusicArtistMetadata" } }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "musicArtistId", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicTrackMetadata": { "type": "object", "properties": { "track": { "$ref": "#/components/schemas/MusicTrack" }, "metadataType": { "type": "object" }, "metadataFormat": { "type": "object" }, "metaKey": { "type": "string" }, "metaValue": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "track", "metaKey", "id", "createdAt", "updatedAt", "deletedAt" ] }, "Library": { "type": "object", "properties": { "id": { "type": "number" }, "libraryId": { "type": "string" }, "name": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } }, "user": { "$ref": "#/components/schemas/User" }, "playbackQueues": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackQueue" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "libraryId", "name", "paths", "user", "playbackQueues", "createdAt", "updatedAt", "deletedAt" ] }, "PlaybackQueue": { "type": "object", "properties": { "queueId": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "type": { "enum": [ "static", "dynamic" ], "type": "string" }, "dynamicType": { "enum": [ "true_shuffle", "house_mix", "encore", "undertow", "fresh_music", "fresh_release" ], "type": "string" }, "seedMediaType": { "enum": [ "music_release", "music_artist" ], "type": "string" }, "seedMediaId": { "type": "string" }, "libraries": { "type": "array", "items": { "$ref": "#/components/schemas/Library" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackQueueItem" } }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "queueId", "user", "type", "dynamicType", "libraries", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PlaybackQueueItem": { "type": "object", "properties": { "queueItemId": { "type": "string" }, "queue": { "$ref": "#/components/schemas/PlaybackQueue" }, "history": { "$ref": "#/components/schemas/MusicHistory" }, "mediaType": { "type": "string" }, "mediaId": { "type": "string" }, "position": { "type": "number" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "queueItemId", "queue", "mediaType", "mediaId", "position", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicHistory": { "type": "object", "properties": { "playbackEntryId": { "type": "string" }, "progress": { "type": "number" }, "track": { "$ref": "#/components/schemas/MusicTrack" }, "queueItem": { "$ref": "#/components/schemas/PlaybackQueueItem" }, "user": { "$ref": "#/components/schemas/User" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "playbackEntryId", "progress", "track", "user", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicTrackWaveform": { "type": "object", "properties": { "track": { "$ref": "#/components/schemas/MusicTrack" }, "version": { "type": "number" }, "binCount": { "type": "number" }, "data": { "type": "object" }, "integratedLufs": { "type": "number" }, "truePeakDb": { "type": "number" }, "silenceLeadIn": { "type": "number" }, "silenceLeadOut": { "type": "number" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "track", "version", "binCount", "data", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicTrack": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/File" }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/MusicArtist" } }, "release": { "$ref": "#/components/schemas/MusicRelease" }, "musicTrackId": { "type": "string" }, "title": { "type": "string" }, "sortTitle": { "type": "string" }, "trackNumber": { "type": "number" }, "discNumber": { "type": "number" }, "duration": { "type": "number" }, "bitrate": { "type": "number" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/MusicTrackMetadata" } }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/MusicHistory" } }, "waveform": { "$ref": "#/components/schemas/MusicTrackWaveform" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "file", "artists", "release", "musicTrackId", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PhotoMetadata": { "type": "object", "properties": { "photo": { "$ref": "#/components/schemas/Photo" }, "metadataType": { "type": "string" }, "metadataFormat": { "type": "string" }, "metaKey": { "type": "string" }, "metaValue": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "photo", "metaKey", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PhotoThumbnail": { "type": "object", "properties": { "thumbnailId": { "type": "string" }, "absolutePath": { "type": "string", "nullable": true }, "relativeSrc": { "type": "string", "nullable": true }, "size": { "type": "string" }, "format": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "bytes": { "type": "number" }, "photo": { "$ref": "#/components/schemas/Photo" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "thumbnailId", "absolutePath", "relativeSrc", "size", "format", "width", "height", "bytes", "photo", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PhotoVariation": { "type": "object", "properties": { "variationId": { "type": "string" }, "absolutePath": { "type": "string", "nullable": true }, "relativeSrc": { "type": "string", "nullable": true }, "format": { "type": "string" }, "bytes": { "type": "number" }, "photo": { "$ref": "#/components/schemas/Photo" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "variationId", "absolutePath", "relativeSrc", "format", "bytes", "photo", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PhotoAlbumMetadata": { "type": "object", "properties": { "photoAlbum": { "$ref": "#/components/schemas/PhotoAlbum" }, "metaKey": { "type": "string" }, "metaValue": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "photoAlbum", "metaKey", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PhotoAlbum": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "photoAlbumId": { "type": "string" }, "name": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoAlbumEntry" } }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoAlbumMetadata" } }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "photoAlbumId", "name", "entries", "metadata", "id", "createdAt", "updatedAt", "deletedAt" ] }, "PhotoAlbumEntry": { "type": "object", "properties": { "photoAlbumEntryId": { "type": "string" }, "photo": { "$ref": "#/components/schemas/Photo" }, "photoAlbum": { "$ref": "#/components/schemas/PhotoAlbum" }, "featured": { "type": "boolean" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "photoAlbumEntryId", "photo", "photoAlbum", "featured", "id", "createdAt", "updatedAt", "deletedAt" ] }, "Photo": { "type": "object", "properties": { "photoId": { "type": "string" }, "file": { "$ref": "#/components/schemas/File" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoMetadata" } }, "thumbnail": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoThumbnail" } }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoVariation" } }, "photoAlbumEntries": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoAlbumEntry" } }, "timestamp": { "type": "number" }, "takenAt": { "format": "date-time", "type": "string" }, "takenOnDay": { "type": "string" }, "modifiedAt": { "format": "date-time", "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "orientation": { "type": "string" }, "deviceMake": { "type": "string" }, "deviceModel": { "type": "string" }, "gpsLat": { "type": "number" }, "gpsLng": { "type": "number" }, "gpsLatRef": { "type": "string" }, "gpsLngRef": { "type": "string" }, "gpsAltitude": { "type": "string" }, "gpsTime": { "type": "string" }, "gpsDate": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "photoId", "file", "metadata", "thumbnail", "variations", "photoAlbumEntries", "timestamp", "takenAt", "takenOnDay", "modifiedAt", "width", "height", "orientation", "deviceMake", "deviceModel", "gpsLat", "gpsLng", "gpsLatRef", "gpsLngRef", "gpsAltitude", "gpsTime", "gpsDate", "id", "createdAt", "updatedAt", "deletedAt" ] }, "Job": { "type": "object", "properties": { "jobId": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "run": { "$ref": "#/components/schemas/Run" }, "type": { "enum": [ "album_art_thumbnails", "photo_variations", "photo_thumbnails", "generate_waveforms", "cloud_backup", "cloud_restore" ], "type": "string" }, "status": { "enum": [ "draft", "preparing", "in_queue", "running", "paused", "canceled", "completed", "errored" ], "type": "string" }, "parameters": { "type": "object" }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/JobTask" } }, "completedTasks": { "type": "number" }, "remainingTasks": { "type": "number" }, "totalTasks": { "type": "number" }, "completedAt": { "format": "date-time", "type": "string" }, "errorMessage": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "jobId", "run", "type", "status", "completedTasks", "remainingTasks", "totalTasks", "completedAt", "errorMessage", "id", "createdAt", "updatedAt", "deletedAt" ] }, "JobTask": { "type": "object", "properties": { "jobTaskId": { "type": "string" }, "job": { "$ref": "#/components/schemas/Job" }, "file": { "$ref": "#/components/schemas/File" }, "type": { "type": "string", "enum": [ "create_album_artwork_thumbnail", "create_photo_thumbnail", "heic_to_jpeg", "generate_track_waveform", "upload_file", "restore_file" ] }, "target": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "in_queue", "running", "paused", "canceled", "completed", "errored" ] }, "completedAt": { "format": "date-time", "type": "string" }, "errorMessage": { "type": "string" }, "results": { "type": "object" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "jobTaskId", "type", "target", "status", "completedAt", "errorMessage", "id", "createdAt", "updatedAt", "deletedAt" ] }, "File": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "run": { "$ref": "#/components/schemas/Run" }, "musicTrack": { "type": "array", "items": { "$ref": "#/components/schemas/MusicTrack" } }, "photo": { "$ref": "#/components/schemas/Photo" }, "fileId": { "type": "string" }, "jobTasks": { "type": "array", "items": { "$ref": "#/components/schemas/JobTask" } }, "absolutePath": { "type": "string" }, "relativePath": { "type": "string" }, "mimeType": { "type": "string" }, "extension": { "type": "string" }, "app": { "type": "string" }, "mediaType": { "type": "string" }, "size": { "type": "number" }, "mtime": { "format": "date-time", "type": "string" }, "contentHash": { "type": "string" }, "hashedAt": { "format": "date-time", "type": "string" }, "lastSeen": { "format": "date-time", "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "user", "run", "fileId", "jobTasks", "absolutePath", "relativePath", "extension", "app", "mediaType", "size", "lastSeen", "id", "createdAt", "updatedAt", "deletedAt" ] }, "MusicTrackComputed": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/File" }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/MusicArtist" } }, "release": { "$ref": "#/components/schemas/MusicRelease" }, "musicTrackId": { "type": "string" }, "title": { "type": "string" }, "sortTitle": { "type": "string" }, "trackNumber": { "type": "number" }, "discNumber": { "type": "number" }, "duration": { "type": "number" }, "bitrate": { "type": "number" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/MusicTrackMetadata" } }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/MusicHistory" } }, "waveform": { "$ref": "#/components/schemas/MusicTrackWaveform" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" }, "numEntries": { "type": "number" }, "playCount": { "type": "number" }, "rating": { "type": "number", "nullable": true } }, "required": [ "file", "artists", "release", "musicTrackId", "id", "createdAt", "updatedAt", "deletedAt" ] }, "CreateLibraryDto": { "type": "object", "properties": { "name": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "paths" ] }, "UpdateLibraryBodyDto": { "type": "object", "properties": { "name": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } } } }, "SetRatingDto": { "type": "object", "properties": { "mediaType": { "type": "string", "enum": [ "music_track" ] }, "mediaId": { "type": "string" }, "rating": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mediaType", "mediaId", "rating" ] }, "Rating": { "type": "object", "properties": { "ratingId": { "type": "string" }, "rating": { "type": "number" }, "mediaType": { "type": "string" }, "mediaId": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "ratingId", "rating", "mediaType", "mediaId", "user", "id", "createdAt", "updatedAt", "deletedAt" ] }, "UpdatePhotoBodyDto": { "type": "object", "properties": { "photoAlbums": { "type": "array", "items": { "type": "number", "minimum": 1 } } }, "required": [ "photoAlbums" ] }, "PhotoAlbumComputed": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "photoAlbumId": { "type": "string" }, "name": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoAlbumEntry" } }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoAlbumMetadata" } }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" }, "numEntries": { "type": "number" }, "size": { "type": "number" }, "thumbnails": { "type": "array", "items": { "type": "object" } } }, "required": [ "photoAlbumId", "name", "entries", "metadata", "id", "createdAt", "updatedAt", "deletedAt" ] }, "CreatePhotoAlbumDto": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "UpdatePhotoAlbumBodyDto": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "PhotoAlbumEntriesBodyDto": { "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "number", "minimum": 1 } } }, "required": [ "photos" ] }, "SetFeaturedPhotoBodyDto": { "type": "object", "properties": { "photo": { "type": "number", "minimum": 1 } }, "required": [ "photo" ] }, "CreateJobDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "album_art_thumbnails", "photo_variations", "photo_thumbnails", "generate_waveforms", "cloud_backup", "cloud_restore" ] }, "parameters": { "type": "object" } }, "required": [ "type" ] }, "UpdateJobDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "preparing", "in_queue", "running", "paused", "canceled", "completed", "errored" ] }, "completedAt": { "format": "date-time", "type": "string" } } }, "CreateBackupConfigDto": { "type": "object", "properties": { "name": { "type": "string" }, "target": { "type": "string", "enum": [ "cardinal" ] }, "scheduleEvery": { "type": "number", "minimum": 1, "maximum": 12 }, "scheduleUnit": { "type": "string", "enum": [ "hour", "day", "week", "month" ] }, "scheduleTimeOfDay": { "type": "string", "pattern": "TIME_OF_DAY_PATTERN" }, "libraryIds": { "type": "array", "items": { "type": "string" } }, "sectionMusic": { "type": "boolean" }, "sectionPhotos": { "type": "boolean" }, "encrypted": { "type": "boolean" }, "passphrase": { "type": "string" }, "storageClass": { "type": "string", "enum": [ "standard", "long_term" ] }, "enabled": { "type": "boolean" } }, "required": [ "name", "scheduleEvery", "scheduleUnit" ] }, "BackupConfig": { "type": "object", "properties": { "backupConfigId": { "type": "string" }, "name": { "type": "string" }, "target": { "type": "string" }, "scheduleEvery": { "type": "number" }, "scheduleUnit": { "type": "object" }, "scheduleAnchorAt": { "format": "date-time", "type": "string" }, "scheduleTimeOfDay": { "type": "string" }, "libraryIds": { "type": "array", "items": { "type": "string" } }, "sectionMusic": { "type": "boolean" }, "sectionPhotos": { "type": "boolean" }, "encrypted": { "type": "boolean" }, "storageClass": { "type": "object" }, "enabled": { "type": "boolean" }, "catchUpMissedRuns": { "type": "boolean" }, "lastRunAt": { "format": "date-time", "type": "string" }, "nextRunAt": { "format": "date-time", "type": "string", "nullable": true }, "lastSnapshotAt": { "format": "date-time", "type": "string" }, "cloudBackupId": { "type": "string" }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "backupConfigId", "name", "target", "scheduleEvery", "scheduleUnit", "scheduleAnchorAt", "libraryIds", "sectionMusic", "sectionPhotos", "encrypted", "storageClass", "enabled", "catchUpMissedRuns", "id", "createdAt", "updatedAt", "deletedAt" ] }, "UpdateBackupConfigDto": { "type": "object", "properties": { "name": { "type": "string" }, "scheduleEvery": { "type": "number", "minimum": 1, "maximum": 12 }, "scheduleUnit": { "type": "string", "enum": [ "hour", "day", "week", "month" ] }, "scheduleTimeOfDay": { "type": "string", "pattern": "TIME_OF_DAY_PATTERN" }, "libraryIds": { "type": "array", "items": { "type": "string" } }, "sectionMusic": { "type": "boolean" }, "sectionPhotos": { "type": "boolean" }, "enabled": { "type": "boolean" }, "storageClass": { "type": "string", "enum": [ "standard", "long_term" ] }, "encrypted": { "type": "boolean" } } }, "TriggerRestoreDto": { "type": "object", "properties": { "snapshotId": { "type": "string" }, "passphrase": { "type": "string" } }, "required": [ "snapshotId" ] }, "CreateMusicHistoryEntryDto": { "type": "object", "properties": { "seconds": { "type": "number" }, "trackId": { "type": "string" }, "queueItemId": { "type": "string" } }, "required": [ "seconds", "trackId", "queueItemId" ] }, "UpdateNotificationDto": { "type": "object", "properties": { "read": { "type": "boolean" } }, "required": [ "read" ] }, "Notification": { "type": "object", "properties": { "notificationId": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "type": { "type": "string" }, "dedupKey": { "type": "string" }, "params": { "type": "object" }, "body": { "type": "string" }, "readAt": { "format": "date-time", "type": "string", "nullable": true }, "id": { "type": "number" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "type": "string" } }, "required": [ "notificationId", "user", "type", "dedupKey", "readAt", "id", "createdAt", "updatedAt", "deletedAt" ] }, "CreatePersonalAccessTokenDto": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100 }, "expiresAt": { "type": "string" } }, "required": [ "label" ] }, "MovePlaybackQueueItemDto": { "type": "object", "properties": { "afterQueueItemId": { "type": "string" } }, "required": [ "afterQueueItemId" ] }, "CreatePlaybackQueueDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "dynamic" ] }, "dynamicType": { "type": "string", "enum": [ "true_shuffle", "house_mix", "encore", "undertow", "fresh_music", "fresh_release" ] }, "seedMediaType": { "type": "string", "enum": [ "music_release", "music_artist" ] }, "seedMediaId": { "type": "string" }, "libraries": { "type": "array", "items": { "type": "object" } }, "staticItems": { "type": "array", "items": { "type": "object" } } }, "required": [ "type" ] }, "ExtendPlaybackQueueDto": { "type": "object", "properties": { "insert": { "type": "string", "enum": [ "next", "end" ] }, "items": { "type": "array", "items": { "type": "object" } } } }, "TelemetryEventDto": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 64, "description": "Dot namespaced event identifier, eg. `page_view`." }, "props": { "type": "object", "additionalProperties": true, "description": "Enumerated values describing the event. Anything free-form is dropped." } }, "required": [ "type" ] }, "IngestTelemetryEventsDto": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/TelemetryEventDto" } } }, "required": [ "events" ] }, "PortMapperStatusResponse": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "disabled", "not_attempted", "active", "failed" ] }, "reason": { "type": "string", "description": "Why the mapping failed. Only present when the state is failed." }, "externalIp": { "type": "string", "nullable": true, "description": "The router-reported external IP. Only present when the state is active." }, "externalPort": { "type": "number", "description": "Only present when the state is active." }, "internalPort": { "type": "number", "description": "Only present when the state is active." }, "leaseExpiresAt": { "type": "string", "description": "ISO timestamp. Only present when the state is active." }, "lastAttemptAt": { "type": "string", "description": "ISO timestamp. Only present when the state is failed." } }, "required": [ "state" ] }, "UpdatePortMapperSettingsDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether to automatically forward the Remote Access port with UPnP. Only works with host networking." } }, "required": [ "enabled" ] }, "ConnectHttpsStatus": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "stopped", "running", "error" ], "description": "State of the Remote Access HTTPS listener, which serves direct connections." }, "port": { "type": "number", "nullable": true, "description": "The port the listener is bound to, once running." }, "certExpiresAt": { "type": "string", "nullable": true, "description": "Expiry of the TLS certificate in use, ISO 8601." }, "lastError": { "type": "string", "nullable": true, "description": "Why the listener could not start or why cert material was rejected." } }, "required": [ "state", "port", "certExpiresAt", "lastError" ] }, "ConnectCertificateStatus": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "none", "pending", "live", "failed" ], "description": "Where certificate issuance for the assigned hostname stands. `none` means Remote Access is disabled or this server has not registered yet, `pending` means an issuance order is expected or under way, `live` means a certificate is in hand, and `failed` means the last attempt was refused or errored. Issuance is a separate asynchronous stage from the control channel, so a `connected` state says nothing about it." }, "reason": { "type": "string", "nullable": true, "description": "Why the last issuance attempt failed, as reported by the Remote Access Server. Null unless `state` is `failed`." }, "retryAt": { "type": "string", "nullable": true, "description": "When issuance will be attempted again, ISO 8601. Null unless `state` is `failed`, and null there too when nothing can be promised." }, "expiresAt": { "type": "string", "nullable": true, "description": "Expiry of the certificate in hand, ISO 8601. Null unless `state` is `live`." } }, "required": [ "state", "reason", "retryAt", "expiresAt" ] }, "ConnectStatusResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether Remote Access is enabled on this server." }, "state": { "type": "string", "enum": [ "disconnected", "connecting", "connected", "auth_failed", "not_approved", "suspended" ], "description": "Live state of the control channel to the Remote Access Server. `not_approved` means the cloud account is waiting on service access for a Remote Access feature, and `suspended` means the account is suspended; both retry on their own." }, "hostname": { "type": "string", "nullable": true, "description": "The hostname assigned by the Remote Access Server, once registered." }, "vanityHostname": { "type": "string", "nullable": true, "description": "The owner-chosen vanity hostname, once the certificate covers it. Preferred over `hostname` when set." }, "signingKeyFingerprint": { "type": "string", "nullable": true, "description": "Truncated SHA-256 fingerprint of the probe signing key, for support diagnostics." }, "tokenExpiresAt": { "type": "string", "nullable": true, "description": "Expiry of the stored cloud credential, ISO 8601." }, "publicPort": { "type": "number", "nullable": true, "description": "The externally reachable port advertised to the Remote Access Server." }, "directUrl": { "type": "string", "nullable": true, "description": "The URL clients use to reach this server directly. Null until a hostname is assigned." }, "relayUrl": { "type": "string", "nullable": true, "description": "The URL clients use to reach this server through the relay." }, "https": { "description": "State of the listener that answers direct connections.", "allOf": [ { "$ref": "#/components/schemas/ConnectHttpsStatus" } ] }, "certificate": { "description": "Where certificate issuance stands. A `directUrl` is only reachable once this is `live`.", "allOf": [ { "$ref": "#/components/schemas/ConnectCertificateStatus" } ] } }, "required": [ "enabled", "state", "hostname", "vanityHostname", "signingKeyFingerprint", "tokenExpiresAt", "publicPort", "directUrl", "relayUrl", "https", "certificate" ] }, "VanityAvailabilityResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "The normalized label the answer is about." }, "available": { "type": "boolean", "description": "Whether this server could claim the label right now." }, "reason": { "type": "string", "description": "Why not, when unavailable. Never says more than `name_unavailable`." } }, "required": [ "name", "available" ] }, "VanityStatusResponse": { "type": "object", "properties": { "labels": { "description": "Every vanity label this server currently holds.", "type": "array", "items": { "type": "string" } }, "primary": { "type": "string", "nullable": true, "description": "The label clients are pointed at, when one is set." }, "state": { "type": "string", "nullable": true, "enum": [ "pending", "live", "failed" ], "description": "Where the certificate covering the labels stands. `pending` means the name is claimed but not yet on a certificate." } }, "required": [ "labels", "primary", "state" ] }, "SetVanityNameDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The vanity label to claim for this server, without any domain suffix." } }, "required": [ "name" ] }, "UptimeLastErrorResponse": { "type": "object", "properties": { "at": { "type": "string", "description": "When this server recorded the failure, ISO 8601." }, "message": { "type": "string", "description": "Why the last check-in did not reach Cardinal Cloud." } }, "required": [ "at", "message" ] }, "UptimeStatusResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether Uptime is on for this server." }, "credential": { "type": "boolean", "description": "Whether this server holds an Uptime credential to check in with." }, "awaitingAccess": { "type": "boolean", "description": "Whether Uptime is on for this server but no credential has been issued to it yet, so no check-ins are being sent." }, "lastAcknowledgedAt": { "type": "string", "nullable": true, "description": "When Cardinal Cloud last acknowledged a check-in, ISO 8601." }, "lastError": { "nullable": true, "description": "The most recent check-in failure. Cleared by the next check-in that succeeds.", "allOf": [ { "$ref": "#/components/schemas/UptimeLastErrorResponse" } ] }, "nextPingAt": { "type": "string", "nullable": true, "description": "When the next check-in is due, ISO 8601. Null while no check-ins are scheduled." }, "pingIntervalSeconds": { "type": "number", "description": "How often this server checks in, in seconds." }, "gracePeriodSeconds": { "type": "number", "description": "How long Cardinal Cloud waits after a missed check-in before emailing, in seconds." }, "recoveryEmail": { "type": "boolean", "description": "Whether Cardinal Cloud also emails once check-ins resume." }, "tokenExpiresAt": { "type": "string", "nullable": true, "description": "Expiry of the stored cloud credential, ISO 8601." } }, "required": [ "enabled", "credential", "awaitingAccess", "lastAcknowledgedAt", "lastError", "nextPingAt", "pingIntervalSeconds", "gracePeriodSeconds", "recoveryEmail", "tokenExpiresAt" ] }, "UptimeDisableResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether Uptime is on for this server." }, "credential": { "type": "boolean", "description": "Whether this server holds an Uptime credential to check in with." }, "awaitingAccess": { "type": "boolean", "description": "Whether Uptime is on for this server but no credential has been issued to it yet, so no check-ins are being sent." }, "lastAcknowledgedAt": { "type": "string", "nullable": true, "description": "When Cardinal Cloud last acknowledged a check-in, ISO 8601." }, "lastError": { "nullable": true, "description": "The most recent check-in failure. Cleared by the next check-in that succeeds.", "allOf": [ { "$ref": "#/components/schemas/UptimeLastErrorResponse" } ] }, "nextPingAt": { "type": "string", "nullable": true, "description": "When the next check-in is due, ISO 8601. Null while no check-ins are scheduled." }, "pingIntervalSeconds": { "type": "number", "description": "How often this server checks in, in seconds." }, "gracePeriodSeconds": { "type": "number", "description": "How long Cardinal Cloud waits after a missed check-in before emailing, in seconds." }, "recoveryEmail": { "type": "boolean", "description": "Whether Cardinal Cloud also emails once check-ins resume." }, "tokenExpiresAt": { "type": "string", "nullable": true, "description": "Expiry of the stored cloud credential, ISO 8601." }, "warnings": { "description": "What could not be said to Cardinal Cloud while turning Uptime off. Uptime is off on this server either way; a non-empty list means the cloud may not know yet.", "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "credential", "awaitingAccess", "lastAcknowledgedAt", "lastError", "nextPingAt", "pingIntervalSeconds", "gracePeriodSeconds", "recoveryEmail", "tokenExpiresAt", "warnings" ] } } } }