kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
802 wiersze
20 KiB
YAML
802 wiersze
20 KiB
YAML
openapi: "3.0.0"
|
|
info:
|
|
description: "Documentation for [Funkwhale](https://funkwhale.audio) API. The API is **not** stable yet."
|
|
version: "1.0.0"
|
|
title: "Funkwhale API"
|
|
|
|
servers:
|
|
- url: https://demo.funkwhale.audio/api/v1
|
|
description: Demo server
|
|
- url: https://{domain}/api/v1
|
|
description: Custom server
|
|
variables:
|
|
domain:
|
|
default: yourdomain
|
|
description: Your Funkwhale Domain
|
|
protocol:
|
|
enum:
|
|
- 'http'
|
|
- 'https'
|
|
default: 'https'
|
|
|
|
components:
|
|
securitySchemes:
|
|
jwt:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: "You can get a token by using the /token endpoint"
|
|
|
|
security:
|
|
- jwt: []
|
|
|
|
paths:
|
|
/token/:
|
|
post:
|
|
tags:
|
|
- "auth"
|
|
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"
|
|
|
|
/artists/:
|
|
get:
|
|
summary: List artists
|
|
tags:
|
|
- "artists"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter artists"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "carpenter"
|
|
- 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"
|
|
/artists/{id}/:
|
|
get:
|
|
summary: Retrieve a single artist
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
|
|
tags:
|
|
- "artists"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Artist"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
/artists/{id}/libraries/:
|
|
get:
|
|
summary: List available user libraries containing work from this artist
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
tags:
|
|
- "artists"
|
|
- "libraries"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/albums/:
|
|
get:
|
|
summary: List albums
|
|
tags:
|
|
- "albums"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter albums"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "carpenter"
|
|
- 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"
|
|
/albums/{id}/:
|
|
get:
|
|
summary: Retrieve a single album
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
|
|
tags:
|
|
- "albums"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Album"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/albums/{id}/libraries/:
|
|
get:
|
|
summary: List available user libraries containing tracks from this album
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
tags:
|
|
- "albums"
|
|
- "libraries"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/tracks/:
|
|
get:
|
|
summary: List tracks
|
|
tags:
|
|
- "tracks"
|
|
parameters:
|
|
- name: "q"
|
|
in: "query"
|
|
default: null
|
|
description: "Search query used to filter tracks"
|
|
schema:
|
|
required: false
|
|
type: "string"
|
|
example: "carpenter"
|
|
- name: "artist"
|
|
in: "query"
|
|
default: null
|
|
description: "Only include tracks by the requested artist"
|
|
schema:
|
|
required: false
|
|
type: "integer"
|
|
format: "int64"
|
|
- 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"
|
|
/tracks/{id}/:
|
|
get:
|
|
summary: Retrieve a single track
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
|
|
tags:
|
|
- "tracks"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/Track"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/tracks/{id}/libraries/:
|
|
get:
|
|
summary: List available user libraries containing given track
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
- $ref: "#/parameters/PageNumber"
|
|
- $ref: "#/parameters/PageSize"
|
|
|
|
tags:
|
|
- "tracks"
|
|
- "libraries"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/licenses/:
|
|
get:
|
|
summary: List licenses
|
|
tags:
|
|
- "licenses"
|
|
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"
|
|
|
|
/licenses/{code}/:
|
|
get:
|
|
summary: Retrieve a single license
|
|
parameters:
|
|
- name: code
|
|
in: path
|
|
description: License code
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: cc0-1.0
|
|
|
|
tags:
|
|
- "licenses"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/License"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
|
|
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"
|
|
|
|
properties:
|
|
mbid:
|
|
type: "string"
|
|
formats: "uuid"
|
|
description: "A musicbrainz ID"
|
|
|
|
definitions:
|
|
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"
|
|
|
|
|
|
Image:
|
|
type: "object"
|
|
properties:
|
|
original:
|
|
type: "string"
|
|
description: "URL to the original image"
|
|
example: "https://mydomain/media/albums/covers/ec2c53aeaac6.jpg"
|
|
small_square_crop:
|
|
type: "string"
|
|
description: "URL to a small, squared thumbnail of the image"
|
|
example: "https://mydomain/media/__sized__/albums/covers/ec2c53aeaac6-crop-c0-5__0-5-50x50-70.jpg"
|
|
|
|
medium_square_crop:
|
|
type: "string"
|
|
description: "URL to a medium, squared thumbnail of the image"
|
|
example: "https://mydomain/media/__sized__/albums/covers/ec2c53aeaac6-crop-c0-5__0-5-200x200-70.jpg"
|
|
|
|
square_crop:
|
|
type: "string"
|
|
description: "URL to a large, squared thumbnail of the image"
|
|
example: "https://mydomain/media/__sized__/albums/covers/ec2c53aeaac6-crop-c0-5__0-5-400x400-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
|
|
name:
|
|
type: "string"
|
|
example: "System of a Down"
|
|
creation_date:
|
|
type: "string"
|
|
format: "date-time"
|
|
Artist:
|
|
type: "object"
|
|
allOf:
|
|
- $ref: "#/definitions/BaseArtist"
|
|
- type: "object"
|
|
properties:
|
|
albums:
|
|
type: "array"
|
|
items:
|
|
$ref: "#/definitions/ArtistAlbum"
|
|
|
|
BaseAlbum:
|
|
type: "object"
|
|
properties:
|
|
mbid:
|
|
required: false
|
|
$ref: "#/properties/mbid"
|
|
id:
|
|
type: "integer"
|
|
format: "int64"
|
|
example: 16
|
|
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/Image"
|
|
|
|
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
|
|
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
|
|
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"
|
|
|
|
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:
|
|
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:
|
|
type: string
|
|
example: "audio/ogg"
|
|
enum:
|
|
- "audio/ogg"
|
|
- "audio/mpeg"
|
|
- "audio/x-flac"
|
|
- "audio/flac"
|
|
extension:
|
|
type: string
|
|
example: "ogg"
|
|
description: "File extension of the upload"
|
|
|
|
listen_url:
|
|
type: "string"
|
|
format: "uri"
|
|
description: "URL to stream the upload"
|
|
|
|
ResourceNotFound:
|
|
type: "object"
|
|
properties:
|
|
detail:
|
|
type: "string"
|
|
example: "Not found."
|