1097 lines
28 KiB
YAML
1097 lines
28 KiB
YAML
# Undocumented endpoints:
|
|
# /api/v1/settings
|
|
# /api/v1/activity
|
|
# /api/v1/listen
|
|
# /api/v1/playlists
|
|
# /api/v1/playlist-tracks
|
|
# /api/v1/favorites
|
|
# /api/v1/search
|
|
# /api/v1/radios
|
|
# /api/v1/history
|
|
# /api/v1/users
|
|
|
|
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: []
|
|
|
|
tags:
|
|
- name: Auth and security
|
|
description: Login, logout 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
|
|
|
|
paths:
|
|
/token/:
|
|
post:
|
|
tags:
|
|
- "Auth and security"
|
|
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:
|
|
- "Library and metadata"
|
|
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:
|
|
- "Library and metadata"
|
|
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:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/albums/:
|
|
get:
|
|
summary: List albums
|
|
tags:
|
|
- "Library and metadata"
|
|
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:
|
|
- "Library and metadata"
|
|
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:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/tracks/:
|
|
get:
|
|
summary: List tracks
|
|
tags:
|
|
- "Library and metadata"
|
|
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:
|
|
parameters:
|
|
- $ref: "#/parameters/ObjectId"
|
|
summary: Retrieve a single track
|
|
|
|
tags:
|
|
- "Library and metadata"
|
|
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:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/LibraryPage"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/licenses/:
|
|
get:
|
|
summary: List licenses
|
|
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"
|
|
|
|
/licenses/{code}/:
|
|
parameters:
|
|
- name: code
|
|
in: path
|
|
description: License code
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: cc0-1.0
|
|
get:
|
|
summary: Retrieve a single license
|
|
|
|
tags:
|
|
- "Library and metadata"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/License"
|
|
404:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/definitions/ResourceNotFound"
|
|
|
|
/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"
|
|
|
|
/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:
|
|
200:
|
|
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"
|
|
|
|
/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
|
|
|
|
/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"
|
|
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"
|
|
|
|
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"
|
|
|
|
responses:
|
|
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"
|
|
import_status:
|
|
type: string
|
|
example: "finished"
|
|
enum:
|
|
- "pending"
|
|
- "finished"
|
|
- "errored"
|
|
- "skipped"
|
|
description: >
|
|
* `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
|
|
|
|
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:
|
|
$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:
|
|
password:
|
|
type: "name"
|
|
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"
|
|
|
|
ResourceNotFound:
|
|
type: "object"
|
|
properties:
|
|
detail:
|
|
type: "string"
|
|
example: "Not found."
|