kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
1844 wiersze
54 KiB
YAML
1844 wiersze
54 KiB
YAML
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 <token>`.
|
|
|
|
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
|
|
|
|
<table>
|
|
<caption>Rate limiting headers</caption>
|
|
<thead>
|
|
<th>Header</th>
|
|
<th>Example value</th>
|
|
<th>Description value</th>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>X-RateLimit-Limit</code></td>
|
|
<td>50</td>
|
|
<td>The number of allowed requests whithin a given period</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>X-RateLimit-Duration</code></td>
|
|
<td>3600</td>
|
|
<td>The time window, in seconds, during which those requests are accounted for.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>X-RateLimit-Scope</code></td>
|
|
<td>login</td>
|
|
<td>The name of the scope as computed for the request</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>X-RateLimit-Remaining</code></td>
|
|
<td>42</td>
|
|
<td>How many requests can be sent with the same scope before the limit applies</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>Retry-After</code> (if <code>X-RateLimit-Remaining</code> is 0)</td>
|
|
<td>3543</td>
|
|
<td>How many seconds to wait before a retry</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>X-RateLimit-Reset</code></td>
|
|
<td>1568126089</td>
|
|
<td>A timestamp indicating when <code>X-RateLimit-Remaining</code> will return to its higher possible value</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>X-RateLimit-ResetSeconds</code></td>
|
|
<td>3599</td>
|
|
<td>How many seconds to wait before <code>X-RateLimit-Remaining</code> returns to its higher possible value</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
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
|