openapi: "3.0.3" info: description: | Interactive documentation for [Funkwhale](https://funkwhale.audio) API. Backward compatibility between minor versions (1.X to 1.Y) is guaranteed for all the endpoints documented here. Usage ----- Click on an endpoint name to inspect its properties, parameters and responses. Use the "Try it out" button to send a real world payload to the endpoint and inspect the corresponding response. OAuth Authentication -------------------- You can register your own OAuth app using the `/api/v1/oauth/apps/` endpoint. Proceed to the standard OAuth flow afterwards: - Our authorize URL is at `/authorize` - Our token acquisition and refresh URL is at `/api/v1/oauth/token` - The list of supported scopes is available by clicking the `Authorize` button in the Swagger UI documentation - Use `urn:ietf:wg:oauth:2.0:oob` as your redirect URI if you want the user to get a copy-pastable authorization code - At the moment, endpoints that deal with admin or moderator-level content are not accessible via OAuth, only through the Web UI You can use our demo server at `https://demo.funkwhale.audio` for testing purposes. Application token authentication -------------------------------- If using OAuth isn't practical and you have an account on the Funkwhale pod, you can create an application by visiting `/settings`. Once the application is created, you can authenticate using its access token in the `Authorization` header, like this: `Authorization: Bearer `. Rate limiting ------------- Depending on server configuration, pods running Funkwhale 0.20 and higher may rate-limit incoming requests to prevent abuse and improve the stability of service. Requests that are dropped because of rate-limiting receive a 429 HTTP response. The limits themselves vary depending on: - The client: anonymous requests are subject to lower limits than authenticated requests - The operation being performed: Write and delete operations, as performed with DELETE, POST, PUT and PATCH HTTP methods are subject to lower limits Those conditions are used to determine the scope of the request, which in turns determine the limit that is applied. For instance, authenticated POST requests are bound to the `authenticated-create` scope, with a default limit of 1000 requests/hour, but anonymous POST requests are bound to the `anonymous-create` scope, with a lower limit of 1000 requests/day. A full list of scopes with their corresponding description, and the current usage data for the client performing the request is available via the `/api/v1/rate-limit` endpoint. Additionally, we include HTTP headers on all API response to ensure API clients can understand: - what scope was bound to a given request - what is the corresponding limit - how much similar requests can be sent before being limited - and how much time they should wait if they have been limited
Rate limiting headers
Header Example value Description value
X-RateLimit-Limit 50 The number of allowed requests whithin a given period
X-RateLimit-Duration 3600 The time window, in seconds, during which those requests are accounted for.
X-RateLimit-Scope login The name of the scope as computed for the request
X-RateLimit-Remaining 42 How many requests can be sent with the same scope before the limit applies
Retry-After (if X-RateLimit-Remaining is 0) 3543 How many seconds to wait before a retry
X-RateLimit-Reset 1568126089 A timestamp indicating when X-RateLimit-Remaining will return to its higher possible value
X-RateLimit-ResetSeconds 3599 How many seconds to wait before X-RateLimit-Remaining returns to its higher possible value
Resources --------- For more targeted guides regarding API usage, and especially authentication, please refer to [https://docs.funkwhale.audio/api.html](https://docs.funkwhale.audio/api.html) version: "1.0.0" title: "Funkwhale API" servers: - url: https://demo.funkwhale.audio description: Demo server - url: https://open.audio description: Real server with real content - url: https://{domain} description: Custom server variables: domain: default: yourdomain description: Your Funkwhale Domain protocol: enum: - 'http' - 'https' default: 'https' components: securitySchemes: oauth2: type: oauth2 description: This API uses OAuth 2 with the Authorization Code flow. You can register an app using the /oauth/apps/ endpoint. flows: authorizationCode: authorizationUrl: /authorize tokenUrl: /api/v1/oauth/token/ refreshUrl: /api/v1/oauth/token/ scopes: "read": "Read-only access to all user data" "write": "Write-only access on all user data" "read:edits": "Read-only access to edits" "write:edits": "Write-only access to edits" "read:favorites": "Read-only access to favorites" "write:favorites": "Write-only access to favorits" "read:filters": "Read-only to to content filters" "write:filters": "Write-only access to content-filters" "read:follows": "Read-only to follows" "write:follows": "Write-only access to follows" "read:libraries": "Read-only access to library and uploads" "write:libraries": "Write-only access to libraries" "read:listenings": "Read-only access to listening history" "write:listenings": "Write-only access to listening history" "read:notifications": "Read-only access to notifications" "write:notifications": "Write-only access to notifications" "read:playlists": "Read-only access to playlists" "write:playlists": "Write-only access to playlists" "read:profile": "Read-only access to profile data" "write:profile": "Write-only access to profile data" "read:radios": "Read-only access to radios" "write:radios": "Write-only access to radios" "read:reports": "Read-only access to reports" "write:reports": "Write-only access to reports" "read:security": "Read-only access security settings" "write:security": "write-only access security settings" jwt: type: http scheme: bearer bearerFormat: JWT description: "You can get a token by using the /token endpoint" security: - jwt: [] - oauth2: [] tags: - name: Auth and security description: Login, logout, rate-limit and authorization endpoints - name: Library and metadata description: Information and metadata about musical and audio entities (albums, tracks, artists, etc.) - name: Uploads and audio content description: Manipulation and uploading of audio files externalDocs: url: https://docs.funkwhale.audio/users/managing.html - name: Channels and subscriptions description: Channel management and subscription externalDocs: url: https://docs.funkwhale.audio/users/upload.html#using-a-channel - name: Content curation description: Favorites, playlists, radios - name: User activity description: Listenings - name: Other description: Other endpoints that don't fit in the categories above paths: /api/v1/oauth/apps/: post: tags: - "Auth and security" summary: Register an OAuth application security: [] responses: 201: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/OAuthApplication" - $ref: "./api/definitions.yml#/OAuthApplicationCreation" requestBody: required: true content: application/json: schema: type: "object" properties: name: type: "string" example: "My Awesome Funkwhale Client" summary: "A human readable name for your app" redirect_uris: type: "string" example: "https://myapp/oauth2/funkwhale" summary: "A list of redirect uris, separated by spaces" scopes: type: "string" summary: "A list of scopes requested by your app, separated by spaces" example: "read write:playlists write:favorites" /api/v1/oauth/token/: post: tags: - "Auth and security" summary: Request an OAuth bearer token in exchange of an authorization_code or a refresh_token security: [] responses: 200: /api/v1/auth/registration/: post: summary: Create an account description: | Register a new account on this instance. An invitation code will be required if sign up is disabled. tags: - "Auth and security" requestBody: required: true content: application/json: schema: type: "object" properties: username: type: "string" example: "alice" email: type: "string" format: "email" invitation: type: "string" example: "INVITECODE" required: false description: An invitation code, required if signups are closed on the instance. password1: type: "string" example: "passw0rd" password2: type: "string" description: Must be identical to password1 example: "passw0rd" responses: 201: $ref: "#/responses/201" /api/v1/auth/password/reset/: post: summary: Request a password reset description: | Request a password reset. An e-mail with reset instructions will be sent to the provided e-mail address, if it's associated with a user account. tags: - "Auth and security" requestBody: required: true content: application/json: schema: type: "object" properties: email: type: "string" format: "email" responses: 200: $ref: "#/responses/200" /api/v1/users/me/: get: summary: Retrive profile information description: | Retrieve profile informations of the current user tags: - "Auth and security" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Me" delete: summary: Delete the user account performing the request tags: - "Auth and security" requestBody: required: true content: application/json: schema: type: "object" properties: confirm: type: "boolean" description: "Must be set to true, to avoid accidental deletion" password: type: "string" description: "The current password of the account" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Me" /api/v1/users/users/change-email/: post: summary: Update the e-mail address associated with a user account tags: - "Auth and security" requestBody: required: true content: application/json: schema: type: "object" properties: email: type: "string" format: "email" password: type: "string" description: "The current password of the account" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Me" /api/v1/rate-limit/: get: summary: Retrive rate-limit information and current usage status tags: - "Auth and security" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/RateLimitStatus" /api/v1/artists/: get: summary: List artists tags: - "Library and metadata" security: - oauth2: - "read:libraries" parameters: - $ref: "./api/parameters.yml#/Search" - allOf: - $ref: "./api/parameters.yml#/Ordering" - default: "-creation_date" schema: required: false type: "string" example: "creation_date" enum: - creation_date - id - name - random - $ref: "./api/parameters.yml#/Playable" - $ref: "./api/parameters.yml#/HasAlbums" - $ref: "./api/parameters.yml#/Library" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Related" - $ref: "./api/parameters.yml#/Scope" - $ref: "./api/parameters.yml#/ContentCategory" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Artist" /api/v1/artists/{id}/: get: summary: Retrieve a single artist parameters: - $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/Refresh" security: - oauth2: - "read:libraries" tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Artist" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/artists/{id}/libraries/: get: summary: List available user libraries containing work from this artist security: - oauth2: - "read:libraries" parameters: - $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/LibraryPage" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/albums/: get: summary: List albums tags: - "Library and metadata" security: - oauth2: - "read:libraries" parameters: - $ref: "./api/parameters.yml#/Search" - name: "artist" in: "query" default: null description: "Only include albums by the requested artist" schema: required: false type: "integer" format: "int64" - allOf: - $ref: "./api/parameters.yml#/Ordering" - default: "-creation_date" schema: required: false type: "string" example: "creation_date" enum: - creation_date - release_date - title - random - $ref: "./api/parameters.yml#/Library" - $ref: "./api/parameters.yml#/Playable" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Related" - $ref: "./api/parameters.yml#/Scope" - $ref: "./api/parameters.yml#/ContentCategory" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Album" /api/v1/albums/{id}/: get: summary: Retrieve a single album parameters: - $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/Refresh" security: - oauth2: - "read:libraries" tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Album" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/albums/{id}/libraries/: get: summary: List available user libraries containing tracks from this album parameters: - $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" security: - oauth2: - "read:libraries" tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/LibraryPage" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/tracks/: get: summary: List tracks tags: - "Library and metadata" security: - oauth2: - "read:libraries" parameters: - $ref: "./api/parameters.yml#/Search" - name: "artist" in: "query" default: null description: "Only include tracks by the requested artist" schema: required: false type: "integer" format: "int64" - name: "favorites" in: "query" default: null description: "filter/exclude tracks favorited by the current user" schema: required: false type: "boolean" - name: "album" in: "query" default: null description: "Only include tracks from the requested album" schema: required: false type: "integer" format: "int64" - name: "license" in: "query" description: "Only include tracks with the given license" default: null schema: example: "cc-by-sa-4.0" required: false type: "string" - allOf: - $ref: "./api/parameters.yml#/Ordering" - default: "-creation_date" schema: required: false type: "string" example: "creation_date" enum: - creation_date - release_date - title - random - $ref: "./api/parameters.yml#/Library" - $ref: "./api/parameters.yml#/Playable" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Related" - $ref: "./api/parameters.yml#/Scope" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Track" /api/v1/tracks/{id}/: get: parameters: - $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/Refresh" summary: Retrieve a single track security: - oauth2: - "read:libraries" tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Track" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/tracks/{id}/libraries/: get: summary: List available user libraries containing given track parameters: - $ref: "./api/parameters.yml#/ObjectId" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" security: - oauth2: - "read:libraries" tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/LibraryPage" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/listen/{uuid}/: get: summary: Download the audio file matching the given track uuid description: | Given a track uuid (and not ID), return the first found audio file accessible by the user making the request. In case of a remote upload, this endpoint will fetch the audio file from the remote and cache it before sending the response. parameters: - name: uuid in: path required: true description: Track uuid schema: type: "string" format: "uuid" - name: to in: query required: false description: | If specified, the endpoint will return a transcoded version of the original audio file. Since transcoding happens on the fly, it can significantly increase response time, and it's recommended to request transcoding only for files that are not playable by the client. This endpoint support bytess-range requests. schema: $ref: "./api/properties.yml#/transcode_options" - name: upload in: query required: false summary: An upload uuid description: | If specified, will return the audio for the given upload uuid. This is useful for tracks that have multiple uploads available. schema: type: string format: uuid - name: token in: query required: false description: | A listen token as returned by /users/me This offers an alternative authentication method for situations where HTTP headers can't be modified to include a Bearer token. schema: type: string tags: - "Library and metadata" responses: 200: content: '*/*': description: "Audio file, as binary data" schema: type: string format: binary 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/licenses/: get: summary: List licenses security: - oauth2: - "read:libraries" tags: - "Library and metadata" parameters: - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/License" /api/v1/licenses/{code}/: get: summary: Retrieve a single license security: - oauth2: - "read:libraries" parameters: - name: code in: path description: License code required: true schema: type: string example: cc0-1.0 tags: - "Library and metadata" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/License" 404: content: application/json: schema: $ref: "./api/definitions.yml#/ResourceNotFound" /api/v1/libraries/: get: summary: List owned libraries tags: - "Uploads and audio content" parameters: - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Scope" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/OwnedLibrary" post: tags: - "Uploads and audio content" description: Create a new library responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/OwnedLibraryCreate" /api/v1/libraries/{uuid}/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Retrieve a library tags: - "Uploads and audio content" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/OwnedLibrary" post: summary: Update a library tags: - "Uploads and audio content" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/OwnedLibraryCreate" responses: 201: content: application/json: schema: $ref: "./api/definitions.yml#/OwnedLibrary" delete: summary: Delete a library and all associated uploads description: | This will delete the library, all associated uploads, follows, and broadcast the event on the federation. tags: - "Uploads and audio content" responses: 204: $ref: "#/responses/204" /api/v1/channels/: get: summary: List channels tags: - "Channels and subscriptions" parameters: - allOf: - $ref: "./api/parameters.yml#/Ordering" - default: "-creation_date" schema: required: false type: "string" example: "creation_date" enum: - creation_date - modification_date - random - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Scope" - $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/Tags" - $ref: "./api/parameters.yml#/Subscribed" - $ref: "./api/parameters.yml#/External" - $ref: "./api/parameters.yml#/ChannelOrdering" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Channel" post: summary: Create a new channel tags: - "Channels and subscriptions" responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/ChannelCreate" /api/v1/channels/metadata-choices: summary: List metadata (locales, itunes categories) for creating and editing channels. tags: - "Channels and subscriptions" get: summary: List channels metadata options tags: - "Channels and subscriptions" responses: 200: content: application/json: schema: type: "object" properties: language: type: "array" items: type: object properties: value: type: string description: ID of the locale in ISO 639 format example: "en" language: type: string example: "English" itunes_category: type: "array" items: type: object properties: value: type: string description: ID of the category example: "Business" label: type: string description: Readable label of the category example: "Business" children: type: array description: Some categories have subcategories items: type: string example: "Entrepreneurship" /api/v1/channels/{uuid}/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Retrieve a channel tags: - "Channels and subscriptions" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Channel" post: summary: Update a channel tags: - "Channels and subscriptions" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/ChannelUpdate" responses: 201: content: application/json: schema: $ref: "./api/definitions.yml#/Channel" delete: summary: Delete a channel and all associated uploads description: | This will delete the channel, all associated uploads, follows, and broadcast the event on the federation. tags: - "Channels and subscriptions" responses: 204: $ref: "#/responses/204" /api/v1/channels/rss-suscribe/: post: summary: Subscribe to a third-party podcast via its RSS feed requestBody: required: true content: application/json: schema: type: "object" properties: url: type: "string" description: URL of the RSS feed tags: - "Channels and subscriptions" responses: 201: content: application/json: schema: $ref: "./api/definitions.yml#/Subscription" /api/v1/channels/{uuid}/rss/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Get the RSS feed of a podcast channel. Only available for channel hosted on the pod where the API is queried. tags: - "Channels and subscriptions" responses: 200: content: application/rss+xml: /api/v1/channels/{uuid}/subscribe/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" post: summary: Subscribe to the given channel tags: - "Channels and subscriptions" responses: 201: content: application/json: schema: $ref: "./api/definitions.yml#/Subscription" /api/v1/channels/{uuid}/unsubscribe/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" post: summary: Unsubscribe from the given channel tags: - "Channels and subscriptions" responses: 204: /api/v1/uploads/: get: summary: List owned uploads tags: - "Uploads and audio content" parameters: - $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Scope" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/OwnedUpload" post: tags: - "Uploads and audio content" description: Upload a new file in a library. The event will be broadcasted on federation, according to the library visibility and followers. responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: multipart/form-data: schema: type: object properties: library: type: string format: uuid description: "The library in which the audio should be stored" import_reference: type: string example: "Import launched via API client on 04/19" source: type: string example: "upload://filename.mp3" audio_file: type: string format: binary import_status: type: string description: "Setting import_status to draft will prevent processing, but allow further modifications to audio and metadata. Once ready, use the PATCH method to set import_status to pending. Default to `pending` if unspecified." default: "pending" enum: - "draft" - "pending" import_metadata: required: false $ref: "./api/definitions.yml#/ImportMetadata" /api/v1/subscriptions/{uuid}/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Retrieve a subscription tags: - "Channels and subscriptions" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Subscription" /api/v1/subscriptions/: get: summary: List subscriptions tags: - "Channels and subscriptions" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Subscription" /api/v1/subscriptions/all/: get: summary: Retrieve all subscriptions in a lightweight format, without pagination tags: - "Channels and subscriptions" responses: 200: content: application/json: schema: type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/SubscriptionsAll" /api/v1/uploads/{uuid}/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Retrieve an upload tags: - "Uploads and audio content" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/OwnedUpload" patch: summary: Update a draft upload description: | This will update a draft upload, before it is processed. All fields supported for `POST /api/v1/uploads` can be updated here. Setting `import_status` to `pending` will trigger processing, and make future modifications impossible. tags: - "Uploads and audio content" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/OwnedUpload" delete: summary: Delete an upload description: | This will delete the upload from the server and broadcast the event on the federation. tags: - "Uploads and audio content" responses: 204: $ref: "#/responses/204" /api/v1/uploads/{uuid}/audio-file-metadata: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Retrieve the tags embedded in the audio file tags: - "Uploads and audio content" responses: 200: content: application/json: schema: type: "object" properties: [] /api/v1/favorites/tracks/: get: tags: - "Content curation" parameters: - $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Scope" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/TrackFavorite" post: summary: Mark the given track as favorite tags: - "Content curation" requestBody: required: true content: application/json: schema: type: "object" properties: track: type: "integer" format: "int64" example: 98 responses: 201: content: application/json: schema: type: "object" properties: id: type: "integer" format: "int64" example: 876 track: type: "integer" format: "int64" example: 98 creation_date: $ref: "./api/properties.yml#/creation_date" /api/v1/favorites/tracks/remove/: post: summary: Remove the given track from favorites tags: - "Content curation" requestBody: required: true content: application/json: schema: type: "object" properties: track: type: "integer" format: "int64" example: 98 responses: 204: $ref: "#/responses/204" ################# # User activity # ################# /api/v1/history/listenings: get: tags: - "User activity" parameters: - $ref: "./api/parameters.yml#/Search" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" - $ref: "./api/parameters.yml#/Scope" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Listening" post: summary: Record a track in your history tags: - "User activity" requestBody: required: true content: application/json: schema: type: "object" properties: track: type: "integer" format: "int64" example: 98 responses: 201: content: application/json: schema: $ref: "./api/definitions.yml#/ListeningCreate" ########## # Others # ########## /api/v1/search: get: tags: - "Other" description: Search artists, tracks, albums and other resources parameters: - $ref: "./api/parameters.yml#/Search" responses: 200: $ref: "#/responses/200" 400: $ref: "#/responses/400" /api/v1/instance/settings: get: tags: - "Other" description: Retrieve pod-level configuration such as description or max playlist size responses: 200: content: application/json: schema: type: "array" description: "List of settings with their id, label and values" items: type: object properties: name: type: "string" description: "Name of the setting" example: "max_channels" section: type: "string" description: "Group of the setting" example: "audio" identifier: type: "string" description: "Unique identifier of the setting" example: "audio__max_channels" default: description: Default value of the setting value: description: Current value of the setting verbose_name: type: "string" description: Human-readable label of the setting help_text: type: "string" description: Human-readable description of the setting field: type: "object" properties: input_type: type: string description: "Input type of the setting" /api/v1/attachments/: post: tags: - "Other" description: Upload a new file as an attachment that can be later associated with other objects. responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary /api/v1/attachments/{uuid}/: parameters: - name: uuid in: path required: true schema: type: "string" format: "uuid" get: summary: Retrieve an attachment tags: - "Other" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Attachment" delete: summary: Delete an attachment tags: - "Other" responses: 204: $ref: "#/responses/204" /api/v1/playlists/: get: summary: List playlists tags: - "Content curation" parameters: - $ref: "./api/parameters.yml#/Search" - allOf: - $ref: "./api/parameters.yml#/Ordering" - default: "-creation_date" schema: required: false type: "string" example: "creation_date" enum: - creation_date - modification_date - id - name - in: query name: artist description: Restrict to playlists containing tracks from the given artist schema: type: "integer" format: "int64" - in: query name: album description: Restrict to playlists containing tracks from the given album schema: type: "integer" format: "int64" - in: query name: track description: Restrict to playlists containing the given track schema: type: "integer" format: "int64" - $ref: "./api/parameters.yml#/Playable" - $ref: "./api/parameters.yml#/PageNumber" - $ref: "./api/parameters.yml#/PageSize" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/Playlist" post: tags: - "Content curation" description: Create a new playlist responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/PlaylistCreate" /api/v1/playlists/{id}/: parameters: - name: id in: path required: true schema: type: "integer" format: "int64" get: summary: Retrieve a playlist tags: - "Content curation" responses: 200: content: application/json: schema: $ref: "./api/definitions.yml#/Playlist" post: summary: Update a playlist tags: - "Content curation" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/PlaylistCreate" responses: 201: content: application/json: schema: $ref: "./api/definitions.yml#/Playlist" delete: description: Delete the playlist tags: - "Content curation" responses: 204: $ref: "#/responses/204" /api/v1/playlists/{id}/tracks: parameters: - name: id in: path required: true schema: type: "integer" format: "int64" get: description: Retrieve all tracks in the playlist tags: - "Content curation" responses: 200: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/PlaylistTrack" /api/v1/playlists/{id}/add: parameters: - name: id in: path required: true schema: type: "integer" format: "int64" post: tags: - "Content curation" summary: Append one or more tracks to a playlist requestBody: required: true content: application/json: schema: type: object properties: tracks: type: array description: An array of track IDs items: type: "integer" format: "int64" example: 13 allow_duplicates: type: boolean default: false description: | Wether to raise an error when the same track is added multiple time in the playlist responses: 201: content: application/json: schema: allOf: - $ref: "./api/definitions.yml#/ResultPage" - type: "object" properties: results: type: "array" items: $ref: "./api/definitions.yml#/PlaylistTrack" /api/v1/playlists/{id}/move: parameters: - name: id in: path required: true schema: type: "integer" format: "int64" post: tags: - "Content curation" summary: Move a track to another index within its playlist requestBody: required: true content: application/json: schema: type: object properties: from: type: "integer" format: "int64" description: Current index of the track to: type: "integer" format: "int64" description: New index of the track responses: 204: /api/v1/playlists/{id}/remove: parameters: - name: id in: path required: true schema: type: "integer" format: "int64" post: tags: - "Content curation" summary: Remove a track from its playlist requestBody: required: true content: application/json: schema: type: object properties: index: type: "integer" format: "int64" description: Index of the track to remove responses: 204: /api/v1/playlists/{id}/clear: parameters: - name: id in: path required: true schema: type: "integer" format: "int64" delete: description: Remove all tracks in the playlist tags: - "Content curation" responses: 204: /api/v1/radios/sessions: post: tags: - "Content curation" description: Start a new radio session responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/RadioSessionCreate" /api/v1/radios/tracks: post: tags: - "Content curation" description: Get a new track for a radio session responses: 201: $ref: "#/responses/201" 400: $ref: "#/responses/400" requestBody: required: true content: application/json: schema: $ref: "./api/definitions.yml#/Track" responses: 200: description: Success 201: description: Successfully created 204: description: Successfully deleted 400: description: Bad request