kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
2113 wiersze
58 KiB
YAML
2113 wiersze
58 KiB
YAML
# Undocumented endpoints:
|
|
# /api/v1/settings
|
|
# /api/v1/activity
|
|
# /api/v1/playlists
|
|
# /api/v1/playlist-tracks
|
|
# /api/v1/search
|
|
# /api/v1/radios
|
|
# /api/v1/history
|
|
|
|
openapi: "3.0.2"
|
|
info:
|
|
description: |
|
|
Interactive documentation for [Funkwhale](https://funkwhale.audio) API.
|
|
|
|
The API is **not** freezed yet, but we will document breaking changes in our changelog,
|
|
and try to avoid those as much as possible.
|
|
|
|
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.
|
|
|
|
Authentication
|
|
--------------
|
|
|
|
To authenticate, use the `/token/` endpoint with a username and password, and copy/paste
|
|
the resulting JWT token in the `Authorize` modal. All subsequent requests made via the interactive
|
|
documentation will be authenticated.
|
|
|
|
If you keep the default server (https://demo.funkwhale.audio), the default username and password
|
|
couple is "demo" and "demo".
|
|
|
|
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://{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:
|
|
# Swagger doesn't support relative URLs yet (cf https://github.com/swagger-api/swagger-ui/pull/5244)
|
|
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:profile": "Read-only access to profile data"
|
|
"read:libraries": "Read-only access to library and uploads"
|
|
"read:playlists": "Read-only access to playlists"
|
|
"read:listenings": "Read-only access to listening history"
|
|
"read:favorites": "Read-only access to favorites"
|
|
"read:radios": "Read-only access to radios"
|
|
"read:edits": "Read-only access to edits"
|
|
"read:notifications": "Read-only access to notifications"
|
|
"read:follows": "Read-only to follows"
|
|
"read:filters": "Read-only to to content filters"
|
|
"write:profile": "Write-only access to profile data"
|
|
"write:libraries": "Write-only access to libraries"
|
|
"write:playlists": "Write-only access to playlists"
|
|
"write:follows": "Write-only access to follows"
|
|
"write:favorites": "Write-only access to favorits"
|
|
"write:notifications": "Write-only access to notifications"
|
|
"write:radios": "Write-only access to radios"
|
|
"write:edits": "Write-only access to edits"
|
|
"write:filters": "Write-only access to content-filters"
|
|
"write:listenings": "Write-only access to listening history"
|
|
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: Content curation
|
|
description: Favorites, playlists, radios
|
|
- name: Other
|
|
description: Other endpoints that don't fit in the categories above
|
|
|
|
paths:
|
|
/api/v1/oauth/apps/:
|
|
post:
|
|
tags:
|
|
- "Auth and security"
|
|
description:
|
|
Register an OAuth application
|
|
security: []
|
|
responses:
|
|
201:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/OAuthApplication"
|
|
- $ref: "#/definitions/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/token/:
|
|
post:
|
|
tags:
|
|
- "Auth and security"
|
|
summary: Get an API token
|
|
description:
|
|
Obtain a JWT token you can use for authenticating your next requests.
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Successfull auth
|
|
'400':
|
|
description: Invalid credentials
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: "object"
|
|
properties:
|
|
username:
|
|
type: "string"
|
|
example: "demo"
|
|
password:
|
|
type: "string"
|
|
example: "demo"
|
|
|
|
/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 email with reset instructions will be sent to the provided email,
|
|
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/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: "#/definitions/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: "#/definitions/RateLimitStatus"
|
|
|
|
/api/v1/artists/:
|
|
get:
|
|
summary: List artists
|
|
tags:
|
|
- "Library and metadata"
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter artists"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
- allOf:
|
|
- $ref: "#/parameters/Ordering"
|
|
- default: "-creation_date"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "creation_date"
|
|
enum:
|
|
- creation_date
|
|
- id
|
|
- name
|
|
- $ref: "#/parameters/Playable"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/Artist"
|
|
/api/v1/artists/{id}/:
|
|
get:
|
|
summary: Retrieve a single artist
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/Refresh"
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Artist"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
/api/v1/artists/{id}/libraries/:
|
|
get:
|
|
summary: List available user libraries containing work from this artist
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/api/v1/albums/:
|
|
get:
|
|
summary: List albums
|
|
tags:
|
|
- "Library and metadata"
|
|
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter albums"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
- name: "artist"
|
|
in: "query"
|
|
default: null
|
|
description: "Only include albums by the requested artist"
|
|
schema:
|
|
required: false
|
|
type: "integer"
|
|
format: "int64"
|
|
- allOf:
|
|
- $ref: "#/parameters/Ordering"
|
|
- default: "-creation_date"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "creation_date"
|
|
enum:
|
|
- creation_date
|
|
- release_date
|
|
- title
|
|
- $ref: "#/parameters/Playable"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/Album"
|
|
/api/v1/albums/{id}/:
|
|
get:
|
|
summary: Retrieve a single album
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/Refresh"
|
|
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Album"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/api/v1/albums/{id}/libraries/:
|
|
get:
|
|
summary: List available user libraries containing tracks from this album
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/api/v1/tracks/:
|
|
get:
|
|
summary: List tracks
|
|
tags:
|
|
- "Library and metadata"
|
|
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter tracks"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
- 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: "#/parameters/Ordering"
|
|
- default: "-creation_date"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "creation_date"
|
|
enum:
|
|
- creation_date
|
|
- release_date
|
|
- title
|
|
- $ref: "#/parameters/Playable"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/Track"
|
|
/api/v1/tracks/{id}/:
|
|
get:
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/Refresh"
|
|
summary: Retrieve a single track
|
|
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Track"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/api/v1/tracks/{id}/libraries/:
|
|
get:
|
|
summary: List available user libraries containing given track
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/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: "#/properties/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
|
|
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
'*/*':
|
|
description: "Audio file, as binary data"
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/api/v1/licenses/:
|
|
get:
|
|
summary: List licenses
|
|
security:
|
|
- oauth2:
|
|
- "read:libraries"
|
|
tags:
|
|
- "Library and metadata"
|
|
parameters:
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/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: "#/definitions/License"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/api/v1/libraries/:
|
|
get:
|
|
summary: List owned libraries
|
|
tags:
|
|
- "Uploads and audio content"
|
|
parameters:
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/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: "#/definitions/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: "#/definitions/OwnedLibrary"
|
|
post:
|
|
summary: Update a library
|
|
tags:
|
|
- "Uploads and audio content"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/OwnedLibraryCreate"
|
|
responses:
|
|
201:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/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:
|
|
- "Uploads and audio content"
|
|
parameters:
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
- $ref: "#/parameters/Scope"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/Channel"
|
|
post:
|
|
summary: Create a new channel
|
|
tags:
|
|
- "Uploads and audio content"
|
|
responses:
|
|
201:
|
|
$ref: "#/responses/201"
|
|
400:
|
|
$ref: "#/responses/400"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ChannelCreate"
|
|
|
|
/api/v1/channels/{uuid}/:
|
|
parameters:
|
|
- name: uuid
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
format: "uuid"
|
|
get:
|
|
summary: Retrieve a channel
|
|
tags:
|
|
- "Uploads and audio content"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Channel"
|
|
post:
|
|
summary: Update a channel
|
|
tags:
|
|
- "Uploads and audio content"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ChannelUpdate"
|
|
responses:
|
|
201:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/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:
|
|
- "Uploads and audio content"
|
|
responses:
|
|
204:
|
|
$ref: "#/responses/204"
|
|
|
|
/api/v1/uploads/:
|
|
get:
|
|
summary: List owned uploads
|
|
tags:
|
|
- "Uploads and audio content"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter uploads"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "Dire straits"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/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: "#/definitions/ImportMetadata"
|
|
|
|
|
|
/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: "#/definitions/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: "#/definitions/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:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter favorites"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
- name: "user"
|
|
in: "query"
|
|
default: null
|
|
description: "Limit results to favorites belonging to the given user"
|
|
schema:
|
|
$ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/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: "#/properties/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"
|
|
|
|
/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: "#/definitions/Attachment"
|
|
delete:
|
|
summary: Delete an attachment
|
|
tags:
|
|
- "Other"
|
|
responses:
|
|
204:
|
|
$ref: "#/responses/204"
|
|
|
|
parameters:
|
|
ObjectId:
|
|
name: id
|
|
in: path
|
|
description: Object ID
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
Ordering:
|
|
name: "ordering"
|
|
in: "query"
|
|
description: "Ordering for the results, prefix with - for DESC ordering"
|
|
|
|
PageNumber:
|
|
in: query
|
|
name: page
|
|
schema:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 1
|
|
default: 1
|
|
minimum: 1
|
|
PageSize:
|
|
in: query
|
|
name: page_size
|
|
schema:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 16
|
|
default: 25
|
|
minimum: 1
|
|
maximum: 25
|
|
Playable:
|
|
name: "playable"
|
|
in: "query"
|
|
default: null
|
|
description: "Filter/exclude resources with playable tracks"
|
|
schema:
|
|
required: false
|
|
type: "boolean"
|
|
Refresh:
|
|
name: "refresh"
|
|
in: "query"
|
|
default: false
|
|
description: "Trigger an ActivityPub fetch to refresh local data"
|
|
schema:
|
|
required: false
|
|
type: "boolean"
|
|
|
|
Scope:
|
|
name: "scope"
|
|
in: "query"
|
|
default: "all"
|
|
description: "Limit the results relative to the user making the request. `me` restrict to owned objects, `all` applies no restriction."
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
enum:
|
|
- "me"
|
|
- "all"
|
|
responses:
|
|
200:
|
|
description: Success
|
|
201:
|
|
description: Successfully created
|
|
204:
|
|
description: Successfully deleted
|
|
400:
|
|
description: Bad request
|
|
|
|
properties:
|
|
mbid:
|
|
type: "string"
|
|
format: "uuid"
|
|
description: "A musicbrainz ID"
|
|
creation_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
privacy_level:
|
|
type: string
|
|
example: "me"
|
|
description: |
|
|
* `me`: private
|
|
* `instance`: accessible by local users
|
|
* `everyone`: public (including over federation)
|
|
enum:
|
|
- "me"
|
|
- "instance"
|
|
- "everyone"
|
|
fid:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "Federation ID"
|
|
example: "https://my.instance/federation/music/libraries/3fa85f64-5717-4562-b3fc-2c963f66afa6"
|
|
audio_mimetype:
|
|
type: string
|
|
example: "audio/ogg"
|
|
enum:
|
|
- "audio/ogg"
|
|
- "audio/mpeg"
|
|
- "audio/x-flac"
|
|
- "audio/flac"
|
|
image_mimetype:
|
|
type: string
|
|
example: "image/png"
|
|
enum:
|
|
- "image/png"
|
|
- "image/jpeg"
|
|
import_status:
|
|
type: string
|
|
example: "finished"
|
|
enum:
|
|
- "draft"
|
|
- "pending"
|
|
- "finished"
|
|
- "errored"
|
|
- "skipped"
|
|
description: |
|
|
* `draft`: waiting for further modifications from the owner
|
|
* `pending`: waiting to be processed by the server
|
|
* `finished`: successfully processed by the server
|
|
* `errored`: couldn't be processed by the server (e.g because of a tagging issue)
|
|
* `skipped`: processed by the server but skipped, because considered as a duplicate of an existing upload
|
|
|
|
transcode_options:
|
|
type: string
|
|
enum:
|
|
- "ogg"
|
|
- "mp3"
|
|
|
|
tags:
|
|
type: array
|
|
description: A list of hashtags associated with a resource
|
|
items:
|
|
type: string
|
|
example: "Rock"
|
|
|
|
definitions:
|
|
OAuthApplication:
|
|
type: "object"
|
|
properties:
|
|
client_id:
|
|
type: "string"
|
|
example: "VKIZWv7FwBq56UMfUtbCSIgSxzUTv1b6nMyOkJvP"
|
|
created:
|
|
type: "string"
|
|
format: "date-time"
|
|
updated:
|
|
type: "string"
|
|
format: "date-time"
|
|
scopes:
|
|
type: "string"
|
|
description: "Coma-separated list of scopes requested by the app"
|
|
|
|
OAuthApplicationCreation:
|
|
type: "object"
|
|
properties:
|
|
client_secret:
|
|
type: "string"
|
|
example: "qnKDX8zjIfC0BG4tUreKlqk3tNtuCfJdGsaEt5MIWrTv0YLLhGI6SGqCjs9kn12gyXtIg4FWfZqWMEckJmolCi7a6qew4LawPWMfnLDii4mQlY1eQG4BJbwPANOrDiTZ"
|
|
redirect_uris:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "Coma-separated list of redirect uris allowed for the app"
|
|
|
|
|
|
ResultPage:
|
|
type: "object"
|
|
properties:
|
|
count:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 42
|
|
description: "The total number of results (all pages included)"
|
|
next:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "Link to the next page of results"
|
|
previous:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "Link to the previous page of results"
|
|
|
|
Attachment:
|
|
type: "object"
|
|
properties:
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
size:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 2787000
|
|
description: "Size of the file, in bytes"
|
|
mimetype:
|
|
$ref: "#/properties/image_mimetype"
|
|
creation_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
urls:
|
|
type: "object"
|
|
properties:
|
|
original:
|
|
type: "string"
|
|
description: "URL to the original image"
|
|
example: "https://mydomain/media/attachments/ec2c53aeaac6.jpg"
|
|
medium_square_crop:
|
|
type: "string"
|
|
description: "URL to a medium, squared thumbnail of the image"
|
|
example: "https://mydomain/media/__sized__/attachments/ec2c53aeaac6-crop-c0-5__0-5-200x200-70.jpg"
|
|
|
|
Actor:
|
|
type: object
|
|
description: "A federation/ ActivityPub actor"
|
|
properties:
|
|
fid:
|
|
type: string
|
|
format: uri
|
|
description: "The actor Federation ID (unique accross federation)"
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
description: "Local ID of the library"
|
|
creation_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
preferred_username:
|
|
type: "string"
|
|
example: "alice"
|
|
name:
|
|
type: string
|
|
example: "Alice Unicorn"
|
|
last_fetch_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
description: "Last time the actor profile was fetched on its origin server"
|
|
domain:
|
|
type: "string"
|
|
format: "hostname"
|
|
example: "open.audio"
|
|
type:
|
|
type: "string"
|
|
example: "Person"
|
|
enum:
|
|
- Person
|
|
- Application
|
|
- Group
|
|
- Organization
|
|
manually_approves_followers:
|
|
type: "boolean"
|
|
full_username:
|
|
type: string
|
|
example: "alice@open.audio"
|
|
|
|
BaseArtist:
|
|
type: "object"
|
|
properties:
|
|
mbid:
|
|
required: false
|
|
$ref: "#/properties/mbid"
|
|
id:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 42
|
|
fid:
|
|
type: string
|
|
format: uri
|
|
description: "The artist Federation ID (unique accross federation)"
|
|
name:
|
|
type: "string"
|
|
example: "System of a Down"
|
|
creation_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
is_local:
|
|
type: "boolean"
|
|
description: "Indicates if the object was initally created locally or on another server"
|
|
|
|
Artist:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/BaseArtist"
|
|
- type: "object"
|
|
properties:
|
|
tracks_count:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 42
|
|
albums:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/ArtistAlbum"
|
|
|
|
BaseAlbum:
|
|
type: "object"
|
|
properties:
|
|
mbid:
|
|
required: false
|
|
$ref: "#/properties/mbid"
|
|
id:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 16
|
|
fid:
|
|
type: string
|
|
format: uri
|
|
description: "The album Federation ID (unique accross federation)"
|
|
artist:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 42
|
|
title:
|
|
type: "string"
|
|
example: "Toxicity"
|
|
creation_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
release_date:
|
|
type: "string"
|
|
required: false
|
|
format: "date"
|
|
example: "2001-01-01"
|
|
is_playable:
|
|
type: "boolean"
|
|
cover:
|
|
$ref: "#/definitions/Attachment"
|
|
is_local:
|
|
type: "boolean"
|
|
description: "Indicates if the object was initally created locally or on another server"
|
|
|
|
Album:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/BaseAlbum"
|
|
- type: "object"
|
|
properties:
|
|
tracks:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/AlbumTrack"
|
|
|
|
ArtistAlbum:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/BaseAlbum"
|
|
- type: "object"
|
|
properties:
|
|
tracks_count:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 16
|
|
|
|
ChannelCreate:
|
|
type: "object"
|
|
properties:
|
|
name:
|
|
type: "string"
|
|
example: "A short, public name for the channel"
|
|
maxLength: 255
|
|
username:
|
|
type: "string"
|
|
example: "aliceandbob"
|
|
description: "The username to associate with the channel, for use over federation. This cannot be changed afterwards."
|
|
summary:
|
|
required: false
|
|
type: "string"
|
|
example: "A short, public description for the channel"
|
|
maxLength: 500
|
|
tags:
|
|
$ref: "#/properties/tags"
|
|
|
|
ChannelUpdate:
|
|
type: "object"
|
|
properties:
|
|
name:
|
|
type: "string"
|
|
example: "A short, public name for the channel"
|
|
maxLength: 255
|
|
summary:
|
|
required: false
|
|
type: "string"
|
|
example: "A short, public description for the channel"
|
|
maxLength: 500
|
|
tags:
|
|
$ref: "#/properties/tags"
|
|
|
|
Channel:
|
|
type: "object"
|
|
properties:
|
|
uuid:
|
|
type: "string"
|
|
format: "uuid"
|
|
creation_date:
|
|
$ref: "#/properties/creation_date"
|
|
artist:
|
|
$ref: "#/definitions/BaseArtist"
|
|
attributed_to:
|
|
$ref: "#/definitions/Actor"
|
|
description: User account owning the channel
|
|
actor:
|
|
$ref: "#/definitions/Actor"
|
|
description: Actor representing the channel over federation
|
|
Library:
|
|
type: "object"
|
|
properties:
|
|
fid:
|
|
type: string
|
|
format: uri
|
|
description: "The library Federation ID (unique accross federation)"
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
description: "Local ID of the library"
|
|
name:
|
|
type: string
|
|
example: "My awesome library"
|
|
description:
|
|
type: string
|
|
nullable: true
|
|
example: "This library contains all the stuff I love!"
|
|
uploads_count:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 687
|
|
privacy_level:
|
|
type: string
|
|
example: "me"
|
|
enum:
|
|
- "me"
|
|
- "instance"
|
|
- "everyone"
|
|
actor:
|
|
$ref: "#/definitions/Actor"
|
|
LibraryPage:
|
|
allOf:
|
|
- $ref: "#/definitions/ResultPage"
|
|
- type: "object"
|
|
properties:
|
|
results:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/Library"
|
|
|
|
License:
|
|
type: "object"
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uri
|
|
example: http://creativecommons.org/publicdomain/zero/1.0/
|
|
description: "The license ID"
|
|
url:
|
|
type: string
|
|
format: uri
|
|
example: http://creativecommons.org/publicdomain/zero/1.0/
|
|
description: "The license url (can be different than the ID)"
|
|
code:
|
|
type: string
|
|
description: "A unique code to identify the license"
|
|
example: cc0-1.0
|
|
redistribute:
|
|
type: boolean
|
|
example: true
|
|
description: "Does the license allow free redistribution?"
|
|
derivative:
|
|
type: boolean
|
|
example: true
|
|
description: "Does the license allow the creation of derivative work?"
|
|
commercial:
|
|
type: boolean
|
|
example: true
|
|
description: "Does the license allow commercial use?"
|
|
attribution:
|
|
type: boolean
|
|
example: false
|
|
description: "Does the license requires crediting the author?"
|
|
copyleft:
|
|
type: boolean
|
|
example: false
|
|
description: "Does the license enforce a similar license of derivative work?"
|
|
|
|
BaseTrack:
|
|
type: "object"
|
|
properties:
|
|
mbid:
|
|
required: false
|
|
$ref: "#/properties/mbid"
|
|
id:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 66
|
|
fid:
|
|
type: string
|
|
format: uri
|
|
description: "The track Federation ID (unique accross federation)"
|
|
artist:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 42
|
|
album:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 16
|
|
title:
|
|
type: "string"
|
|
example: "Chop Suey!"
|
|
position:
|
|
required: false
|
|
description: "Position of the track in the album"
|
|
type: "number"
|
|
minimum: 1
|
|
example: 1
|
|
disc_number:
|
|
required: false
|
|
type: "number"
|
|
minimum: 1
|
|
example: 1
|
|
listen_url:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "URL to stream the track"
|
|
copyright:
|
|
type: "string"
|
|
example: "Creative Commons Attribution-NonCommercial-NoDerivatives 4.0: http://creativecommons.org/licenses/by-nc-nd/4.0/"
|
|
description: "Copyright information as extracted from upload tags"
|
|
license:
|
|
type: "string"
|
|
description: "Identifier of the license that is linked to the track"
|
|
example: "cc-by-nc-nd-4.0"
|
|
is_local:
|
|
type: "boolean"
|
|
description: "Indicates if the object was initally created locally or on another server"
|
|
|
|
AlbumTrack:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/BaseTrack"
|
|
- type: "object"
|
|
properties:
|
|
artist:
|
|
$ref: "#/definitions/BaseArtist"
|
|
uploads:
|
|
type: "array"
|
|
description: "List of uploads associated with this track"
|
|
items:
|
|
$ref: "#/definitions/Upload"
|
|
Track:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/BaseTrack"
|
|
- type: "object"
|
|
properties:
|
|
album:
|
|
$ref: "#/definitions/Album"
|
|
artist:
|
|
$ref: "#/definitions/BaseArtist"
|
|
uploads:
|
|
type: "array"
|
|
description: "List of uploads associated with this track"
|
|
items:
|
|
$ref: "#/definitions/Upload"
|
|
Upload:
|
|
type: "object"
|
|
properties:
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
size:size:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 278987000
|
|
description: "Size of the file, in bytes"
|
|
duration:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 184
|
|
description: "Duration of the audio, in seconds"
|
|
bitrate:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 128000
|
|
description: "Bitrate of the file, in bytes/s"
|
|
mimetype:
|
|
$ref: "#/properties/audio_mimetype"
|
|
extension:
|
|
type: string
|
|
example: "ogg"
|
|
description: "File extension of the upload"
|
|
filename:
|
|
type: "string"
|
|
example: "Myfile.mp3"
|
|
listen_url:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "URL to stream the upload"
|
|
|
|
OwnedLibraryCreate:
|
|
type: "object"
|
|
properties:
|
|
name:
|
|
type: "string"
|
|
example: "My new library"
|
|
description:
|
|
required: false
|
|
type: "string"
|
|
example: "Lots of interesting content"
|
|
privacy_level:
|
|
$ref: "#/properties/privacy_level"
|
|
|
|
OwnedLibrary:
|
|
type: "object"
|
|
properties:
|
|
uuid:
|
|
type: string
|
|
format: uuid
|
|
fid:
|
|
$ref: "#/properties/fid"
|
|
name:
|
|
type: "string"
|
|
example: "My Creative Commons library"
|
|
description:
|
|
type: "string"
|
|
example: "All content is under CC-BY"
|
|
creation_date:
|
|
$ref: "#/properties/creation_date"
|
|
privacy_level:
|
|
$ref: "#/properties/privacy_level"
|
|
uploads_count:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 34
|
|
size:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 678917000
|
|
description: "Total size of uploads in the library, in bytes"
|
|
|
|
OwnedUpload:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/Upload"
|
|
- type: "object"
|
|
properties:
|
|
import_status:
|
|
$ref: "#/properties/import_status"
|
|
track:
|
|
$ref: "#/definitions/Track"
|
|
library:
|
|
$ref: "#/definitions/OwnedLibrary"
|
|
source:
|
|
type: "string"
|
|
example: "upload://myfile.mp3"
|
|
import_reference:
|
|
type: "string"
|
|
example: "Import launched via web UI on 03/18"
|
|
import_metadata:
|
|
$ref: "#/definitions/ImportMetadata"
|
|
|
|
ImportMetadata:
|
|
type: "object"
|
|
description: "Import metadata to override values from ID3/embedded audio tags"
|
|
properties:
|
|
title:
|
|
type: "string"
|
|
example: "My Track"
|
|
required: true
|
|
mbid:
|
|
$ref: "#/properties/mbid"
|
|
required: false
|
|
copyright:
|
|
type: "string"
|
|
example: "Alice, 2018"
|
|
description: "Copyright information"
|
|
required: false
|
|
license:
|
|
type: "string"
|
|
example: "cc-by-sa-4.0"
|
|
required: false
|
|
description: A license code, as returned by /api/v1/licenses
|
|
tags:
|
|
$ref: "#/properties/tags"
|
|
required: false
|
|
position:
|
|
description: "Position of the track in the album or channel"
|
|
type: "number"
|
|
minimum: 1
|
|
example: 1
|
|
|
|
TrackFavorite:
|
|
type: "object"
|
|
properties:
|
|
id:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 876
|
|
track:
|
|
$ref: "#/definitions/Track"
|
|
user:
|
|
$ref: "#/definitions/User"
|
|
creation_date:
|
|
$ref: "#/properties/creation_date"
|
|
User:
|
|
type: "object"
|
|
properties:
|
|
id:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 23
|
|
username:
|
|
type: "string"
|
|
example: "alice"
|
|
name:
|
|
type: "string"
|
|
example: "Alice Kingsley"
|
|
avatar:
|
|
$ref: "#/definitions/Avatar"
|
|
|
|
Me:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/User"
|
|
- type: "object"
|
|
properties:
|
|
full_username:
|
|
type: "string"
|
|
description: Full username, for use on federation
|
|
example: "alice@yourdomain.com"
|
|
email:
|
|
type: "string"
|
|
format: "email"
|
|
description: Email address associated with the account
|
|
example: "alice@email.provider"
|
|
is_staff:
|
|
type: "boolean"
|
|
example: false
|
|
is_superuser:
|
|
type: "boolean"
|
|
example: false
|
|
date_joined:
|
|
type: "string"
|
|
format: "date-time"
|
|
privacy_level:
|
|
$ref: "#/properties/privacy_level"
|
|
description: Default privacy-level associated with the user account
|
|
quota_status:
|
|
$ref: "#/definitions/QuotaStatus"
|
|
permissions:
|
|
$ref: "#/definitions/Permissions"
|
|
Avatar:
|
|
type: "object"
|
|
properties:
|
|
original:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "Original image URL"
|
|
example: "http://yourinstance/media/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996.jpg"
|
|
square_crop:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "400x400 thumbnail URL"
|
|
example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-400x400-70.jpg"
|
|
small_square_crop:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "50x50 thumbnail URL"
|
|
example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-50x50-70.jpg"
|
|
medium_square_crop:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "200x200 thumbnail URL"
|
|
example: "http://yourinstance/media/__sized__/users/avatars/92/49/60/b3c-4736-43b3-bb5c-ed7a99ac6996-crop-c0-5__0-5-200x200-70.jpg"
|
|
QuotaStatus:
|
|
type: "object"
|
|
properties:
|
|
max:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space allocated to this user, in MB
|
|
example: 5000
|
|
remaining:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Remaining storage space for this user, in MB
|
|
example: 4600
|
|
current:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space used by this user, in MB
|
|
example: 400
|
|
skipped:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space occupied by uploads with "skipped" import status, in MB
|
|
example: 30
|
|
finished:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space occupied by uploads with "finished" import status, in MB
|
|
example: 350
|
|
pending:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space occupied by uploads with "pending" import status, in MB
|
|
example: 15
|
|
draft:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space occupied by uploads with "draft" import status, in MB
|
|
example: 8
|
|
errored:
|
|
type: "integer"
|
|
format: "int64"
|
|
description: Storage space occupied by uploads with "errored" import status, in MB
|
|
example: 5
|
|
Permissions:
|
|
type: "object"
|
|
properties:
|
|
library:
|
|
type: "boolean"
|
|
example: false
|
|
description: A boolean indicating if the user can manage the instance library
|
|
moderation:
|
|
type: "boolean"
|
|
example: false
|
|
description: A boolean indicating if the user has moderation permission
|
|
settings:
|
|
type: "boolean"
|
|
example: false
|
|
description: A boolean indicating if the user can manage instance settings and users
|
|
RateLimitStatus:
|
|
type: "object"
|
|
properties:
|
|
enabled:
|
|
type: "boolean"
|
|
example: true
|
|
description: A boolean indicating if rate-limiting is enabled on the server
|
|
ident:
|
|
type: "object"
|
|
description: Client-related data
|
|
properties:
|
|
type:
|
|
type: string
|
|
example: "anonymous"
|
|
enum:
|
|
- "authenticated"
|
|
- "anonymous"
|
|
id:
|
|
type: string
|
|
example: "92.143.42"
|
|
description: An address IP or user ID identifying the client
|
|
scopes:
|
|
type: "array"
|
|
items:
|
|
type: "object"
|
|
description: Rate-limit scope configuration and usage
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: "password-reset"
|
|
description:
|
|
type: string
|
|
example: "Password reset request"
|
|
rate:
|
|
type: string
|
|
example: "30/day"
|
|
limit:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 30
|
|
duration:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 86400
|
|
remaining:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 28
|
|
description: How many requests can be sent with the same scope before the limit applies
|
|
reset:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 1568126189
|
|
description: A timestamp indicating when <code>remaining</code> will return to its higher possible value
|
|
reset_seconds:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 86267
|
|
description: How many seconds to wait before <code>remaining</code> returns to its higher possible value
|
|
available:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 1568126089
|
|
description: A timestamp indicating when the client can retry
|
|
available_seconds:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 54
|
|
description: How many seconds to wait before a retry
|
|
|
|
ResourceNotFound:
|
|
type: "object"
|
|
properties:
|
|
detail:
|
|
type: "string"
|
|
example: "Not found."
|