From 2d0de0bfff782ba4b438c8a0c4f1d99e66bb3d05 Mon Sep 17 00:00:00 2001 From: Agate Date: Sun, 5 Jul 2020 11:00:04 +0200 Subject: [PATCH] API docs --- dev.yml | 1 + docs/api/definitions.yml | 897 +++++++++++++++++++++++ docs/api/parameters.yml | 118 +++ docs/api/properties.yml | 100 +++ docs/build_swagger.sh | 1 + docs/swagger.yml | 1467 ++++++++------------------------------ 6 files changed, 1430 insertions(+), 1154 deletions(-) create mode 100644 docs/api/definitions.yml create mode 100644 docs/api/parameters.yml create mode 100644 docs/api/properties.yml diff --git a/dev.yml b/dev.yml index c22689304..c6d48c78a 100644 --- a/dev.yml +++ b/dev.yml @@ -161,6 +161,7 @@ services: - "8002:8080" volumes: - "./docs/swagger.yml:/usr/share/nginx/html/swagger.yml" + - "./docs/api:/usr/share/nginx/html/api" # minio: # image: minio/minio diff --git a/docs/api/definitions.yml b/docs/api/definitions.yml new file mode 100644 index 000000000..4903b2c39 --- /dev/null +++ b/docs/api/definitions.yml @@ -0,0 +1,897 @@ + + +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.yml#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.yml#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: "#/BaseArtist" + - type: "object" + properties: + tracks_count: + type: "integer" + format: "int64" + example: 42 + albums: + type: "array" + items: + $ref: "#/ArtistAlbum" + +BaseAlbum: + type: "object" + properties: + mbid: + required: false + $ref: "./properties.yml#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: "#/Attachment" + is_local: + type: "boolean" + description: "Indicates if the object was initally created locally or on another server" + +Album: + type: "object" + allOf: + - $ref: "#/BaseAlbum" + - type: "object" + properties: + tracks: + type: "array" + items: + $ref: "#/AlbumTrack" + +ArtistAlbum: + type: "object" + allOf: + - $ref: "#/BaseAlbum" + - type: "object" + properties: + tracks_count: + type: "integer" + format: "int64" + example: 16 + +ChannelMetadata: + type: "object" + properties: + itunes_category: + type: string + example: Comedy + description: Itunes category (see `/api/v1/channels/metadata-choices`) for allowed values + itunes_subcategory: + type: string + example: Improv + description: Itunes subcategory (see `/api/v1/channels/metadata-choices`) for allowed values + language: + type: string + example: en + description: Language of the content, in ISO 639 format (see `/api/v1/channels/metadata-choices`) for allowed values + owner_name: + type: string + example: "Alice" + description: Used to make the channel compatible with other platforms (iTunes, Spotify, etc.) + owner_email: + type: string + example: "alice@example.com" + description: Used to make the channel compatible with other platforms (iTunes, Spotify, etc.) + +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." + description: + $ref: "./properties.yml#description" + tags: + $ref: "./properties.yml#tags" + content_category: + $ref: "./properties.yml#content_category" + cover: + type: string + format: uuid + metadata: + $ref: "#ChannelMetadata" +ChannelUpdate: + type: "object" + properties: + name: + type: "string" + example: "A short, public name for the channel" + maxLength: 255 + description: + $ref: "./properties.yml#description" + tags: + $ref: "./properties.yml#tags" + cover: + type: string + format: uuid + metadata: + $ref: "#/ChannelMetadata" + +Channel: + type: "object" + properties: + uuid: + type: "string" + format: "uuid" + creation_date: + $ref: "./properties.yml#creation_date" + artist: + $ref: "#/BaseArtist" + attributed_to: + $ref: "#/Actor" + description: User account owning the channel + actor: + $ref: "#/Actor" + description: Actor representing the channel over federation + +Subscription: + type: "object" + properties: + approved: + type: "string" + fid: + $ref: "./properties.yml#fid" + uuid: + type: "string" + format: "uuid" + creation_date: + $ref: "./properties.yml#creation_date" + channel: + $ref: "#/Channel" + +SubscriptionsAll: + type: "object" + properties: + uuid: + type: "string" + format: "uuid" + channel: + type: "string" + format: "uuid" + +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: "#/Actor" +LibraryPage: + allOf: + - $ref: "#/ResultPage" + - type: "object" + properties: + results: + type: "array" + items: + $ref: "#/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.yml#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: "#/BaseTrack" + - type: "object" + properties: + artist: + $ref: "#/BaseArtist" + uploads: + type: "array" + description: "List of uploads associated with this track" + items: + $ref: "#/Upload" +Track: + type: "object" + allOf: + - $ref: "#/BaseTrack" + - type: "object" + properties: + album: + $ref: "#/Album" + artist: + $ref: "#/BaseArtist" + uploads: + type: "array" + description: "List of uploads associated with this track" + items: + $ref: "#/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.yml#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.yml#privacy_level" + +OwnedLibrary: + type: "object" + properties: + uuid: + type: string + format: uuid + fid: + $ref: "./properties.yml#fid" + name: + type: "string" + example: "My Creative Commons library" + description: + type: "string" + example: "All content is under CC-BY" + creation_date: + $ref: "./properties.yml#creation_date" + privacy_level: + $ref: "./properties.yml#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: "#/Upload" + - type: "object" + properties: + import_status: + $ref: "./properties.yml#import_status" + track: + $ref: "#/Track" + library: + $ref: "#/OwnedLibrary" + source: + type: "string" + example: "upload://myfile.mp3" + import_reference: + type: "string" + example: "Import launched via web UI on 03/18" + import_metadata: + $ref: "#/ImportMetadata" + +Playlist: + type: "object" + properties: + id: + type: "integer" + format: "int64" + example: 42 + name: + type: "string" + description: Name of the playlist + example: "Move your body" + duration: + type: "integer" + format: "int64" + description: Duration of the playlist, in seconds + example: 3600 + tracks_count: + type: "integer" + format: "int64" + description: Number of tracks in the playlist + example: 76 + privacy_level: + $ref: "./properties.yml#privacy_level" + actor: + $ref: "#/Actor" + description: Actor owning the playlist + creation_date: + $ref: "./properties.yml#creation_date" + modification_date: + $ref: "./properties.yml#modification_date" + + +PlaylistCreate: + type: "object" + properties: + name: + type: "string" + description: Name of the playlist + example: "Move your body" + privacy_level: + $ref: "./properties.yml#privacy_level" + +PlaylistTrack: + type: "object" + properties: + id: + type: "integer" + format: "int64" + example: 42 + index: + type: "integer" + format: "int64" + example: 16 + description: Position of the track in the playlist + creation_date: + $ref: "./properties.yml#creation_date" + track: + $ref: "#/Track" + +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.yml#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.yml#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: "#/Track" + user: + $ref: "#/User" + creation_date: + $ref: "./properties.yml#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: "#/Avatar" + +Me: + type: "object" + allOf: + - $ref: "#/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.yml#privacy_level" + description: Default privacy-level associated with the user account + quota_status: + $ref: "#/QuotaStatus" + permissions: + $ref: "#/Permissions" + tokens: + type: object + properties: + listen: + type: string + description: | + A token that can be passed in the querystring, when playing + a file from the /api/v1/listen endpoint. Example: + /api/v1/listen/uuid/?token=foo + + This is especially useful in situations where authentication + via request headers isn't possible. + + The token expires after 3 days by default. +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 remaining will return to its higher possible value + reset_seconds: + type: "integer" + format: "int64" + example: 86267 + description: How many seconds to wait before remaining 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." diff --git a/docs/api/parameters.yml b/docs/api/parameters.yml new file mode 100644 index 000000000..e8fdd076b --- /dev/null +++ b/docs/api/parameters.yml @@ -0,0 +1,118 @@ +ChannelOrdering: + - $ref: "#/parameters/Ordering" + - default: "-creation_date" + schema: + required: false + type: "string" + example: "-creation_date" + enum: + - creation_date + - artist__modification_date + +External: + name: "external" + in: "query" + default: null + description: "Filter/exclude channels created from a third-party, non-Funkwhale RSS feed" + schema: + required: false + type: "boolean" + + +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 to a given user or pod: + - Use `all` (or do not specify the property to disable scope filtering) + - Use `me` to retrieve content relative to the current user + - Use `actor:alice@example.com` to retrieve content relative to the account `alice@example.com + - Use `domain:example.com` to retrieve content relative to the domain `example.com + schema: + required: false + type: "string" + enum: + - "me" + - "all" + - "actor:alice@example.com" + - "domain:example.com" + +Search: + name: "q" + in: "query" + default: "all" + description: "Limit the results to the corresponding search query" + schema: + required: false + type: "string" + example: "Bonobo" + +Subscribed: + name: "subscribed" + in: "query" + description: "Limit or exclude results with a matching subsription from the current user" + schema: + required: false + type: boolean + +Tags: + name: "tag" + in: "query" + description: "Limit the results to the corresponding tags. May be used multiple times, to retrieve objects matching al provided tags" + schema: + required: false + type: array + collectionFormat: csv + example: + - rock + - metal diff --git a/docs/api/properties.yml b/docs/api/properties.yml new file mode 100644 index 000000000..1133a0937 --- /dev/null +++ b/docs/api/properties.yml @@ -0,0 +1,100 @@ + +description: + type: object + description: Text content associated with another resource, like and artist or channel. + properties: + text: + type: string + example: "This is **me**" + description: "The raw user input" + content_type: + type: string + enum: + - text/markdown + - text/plain + - text/html + description: "The raw user input" + html: + type: string + description: "HTML output based on user input" + readOnly: true + +mbid: + type: "string" + format: "uuid" + description: "A musicbrainz ID" +creation_date: + type: "string" + format: "date-time" + description: "Creation date of the resource" + +modification_date: + type: "string" + format: "date-time" + description: "Last modification date of th resource" +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" + +content_category: + type: "string" + description: Used to what kind of content is published in a chanel + enum: + - music + - podcast + - other diff --git a/docs/build_swagger.sh b/docs/build_swagger.sh index 13ae21b06..8c0d32e55 100755 --- a/docs/build_swagger.sh +++ b/docs/build_swagger.sh @@ -6,4 +6,5 @@ rm -rf $TARGET_PATH /tmp/swagger-ui git clone --branch="v$SWAGGER_VERSION" --depth=1 "https://github.com/swagger-api/swagger-ui.git" /tmp/swagger-ui mv /tmp/swagger-ui/dist $TARGET_PATH cp swagger.yml $TARGET_PATH +cp -r api $TARGET_PATH/api sed -i "s,http://petstore.swagger.io/v2/swagger.json,swagger.yml,g" $TARGET_PATH/index.html diff --git a/docs/swagger.yml b/docs/swagger.yml index c00ab184b..27892fe67 100644 --- a/docs/swagger.yml +++ b/docs/swagger.yml @@ -1,7 +1,6 @@ # Undocumented endpoints: # /api/v1/settings # /api/v1/activity -# /api/v1/playlists # /api/v1/playlist-tracks # /api/v1/search # /api/v1/radios @@ -205,8 +204,8 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/OAuthApplication" - - $ref: "#/definitions/OAuthApplicationCreation" + - $ref: "./api/definitions.yml#OAuthApplication" + - $ref: "./api/definitions.yml#OAuthApplicationCreation" requestBody: required: true content: @@ -323,7 +322,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/Me" + $ref: "./api/definitions.yml#Me" /api/v1/rate-limit/: get: @@ -336,7 +335,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/RateLimitStatus" + $ref: "./api/definitions.yml#RateLimitStatus" /api/v1/artists/: get: @@ -348,9 +347,9 @@ paths: - "read:libraries" parameters: - - $ref: "#/parameters/Search" + - $ref: "./api/parameters.yml#Search" - allOf: - - $ref: "#/parameters/Ordering" + - $ref: "./api/parameters.yml#Ordering" - default: "-creation_date" schema: required: false @@ -360,10 +359,10 @@ paths: - creation_date - id - name - - $ref: "#/parameters/Playable" - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Scope" + - $ref: "./api/parameters.yml#Playable" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" + - $ref: "./api/parameters.yml#Scope" responses: 200: @@ -371,19 +370,19 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/Artist" + $ref: "./api/definitions.yml#Artist" /api/v1/artists/{id}/: get: summary: Retrieve a single artist parameters: - - $ref: "#/parameters/ObjectId" - - $ref: "#/parameters/Refresh" + - $ref: "./api/parameters.yml#ObjectId" + - $ref: "./api/parameters.yml#Refresh" security: - oauth2: - "read:libraries" @@ -394,12 +393,12 @@ paths: content: application/json: schema: - $ref: "#/definitions/Artist" + $ref: "./api/definitions.yml#Artist" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#ResourceNotFound" /api/v1/artists/{id}/libraries/: get: summary: List available user libraries containing work from this artist @@ -407,9 +406,9 @@ paths: - oauth2: - "read:libraries" parameters: - - $ref: "#/parameters/ObjectId" - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" + - $ref: "./api/parameters.yml#ObjectId" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" tags: - "Library and metadata" @@ -418,12 +417,12 @@ paths: content: application/json: schema: - $ref: "#/definitions/LibraryPage" + $ref: "./api/definitions.yml#LibraryPage" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#ResourceNotFound" /api/v1/albums/: get: @@ -436,7 +435,7 @@ paths: - "read:libraries" parameters: - - $ref: "#/parameters/Search" + - $ref: "./api/parameters.yml#Search" - name: "artist" in: "query" default: null @@ -446,7 +445,7 @@ paths: type: "integer" format: "int64" - allOf: - - $ref: "#/parameters/Ordering" + - $ref: "./api/parameters.yml#Ordering" - default: "-creation_date" schema: required: false @@ -456,10 +455,10 @@ paths: - creation_date - release_date - title - - $ref: "#/parameters/Playable" - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Scope" + - $ref: "./api/parameters.yml#Playable" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" + - $ref: "./api/parameters.yml#Scope" responses: 200: @@ -467,19 +466,19 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/Album" + $ref: "./api/definitions.yml#Album" /api/v1/albums/{id}/: get: summary: Retrieve a single album parameters: - - $ref: "#/parameters/ObjectId" - - $ref: "#/parameters/Refresh" + - $ref: "./api/parameters.yml#ObjectId" + - $ref: "./api/parameters.yml#Refresh" security: - oauth2: @@ -491,20 +490,20 @@ paths: content: application/json: schema: - $ref: "#/definitions/Album" + $ref: "./api/definitions.yml#Album" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#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" + - $ref: "./api/parameters.yml#ObjectId" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" security: - oauth2: @@ -516,12 +515,12 @@ paths: content: application/json: schema: - $ref: "#/definitions/LibraryPage" + $ref: "./api/definitions.yml#LibraryPage" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#ResourceNotFound" /api/v1/tracks/: get: @@ -534,7 +533,7 @@ paths: - "read:libraries" parameters: - - $ref: "#/parameters/Search" + - $ref: "./api/parameters.yml#Search" - name: "artist" in: "query" default: null @@ -567,7 +566,7 @@ paths: required: false type: "string" - allOf: - - $ref: "#/parameters/Ordering" + - $ref: "./api/parameters.yml#Ordering" - default: "-creation_date" schema: required: false @@ -577,10 +576,10 @@ paths: - creation_date - release_date - title - - $ref: "#/parameters/Playable" - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Scope" + - $ref: "./api/parameters.yml#Playable" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" + - $ref: "./api/parameters.yml#Scope" responses: 200: @@ -588,18 +587,18 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/Track" + $ref: "./api/definitions.yml#Track" /api/v1/tracks/{id}/: get: parameters: - - $ref: "#/parameters/ObjectId" - - $ref: "#/parameters/Refresh" + - $ref: "./api/parameters.yml#ObjectId" + - $ref: "./api/parameters.yml#Refresh" summary: Retrieve a single track security: @@ -612,20 +611,20 @@ paths: content: application/json: schema: - $ref: "#/definitions/Track" + $ref: "./api/definitions.yml#Track" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#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" + - $ref: "./api/parameters.yml#ObjectId" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" security: - oauth2: - "read:libraries" @@ -636,12 +635,12 @@ paths: content: application/json: schema: - $ref: "#/definitions/LibraryPage" + $ref: "./api/definitions.yml#LibraryPage" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#ResourceNotFound" /api/v1/listen/{uuid}/: get: summary: Download the audio file matching the given track uuid @@ -673,7 +672,7 @@ paths: This endpoint support bytess-range requests. schema: - $ref: "#/properties/transcode_options" + $ref: "./api/properties.yml#transcode_options" - name: upload in: query required: false @@ -686,6 +685,16 @@ paths: 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" @@ -701,7 +710,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#ResourceNotFound" /api/v1/licenses/: get: @@ -712,21 +721,21 @@ paths: tags: - "Library and metadata" parameters: - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" responses: 200: content: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/License" + $ref: "./api/definitions.yml#License" /api/v1/licenses/{code}/: get: @@ -750,12 +759,12 @@ paths: content: application/json: schema: - $ref: "#/definitions/License" + $ref: "./api/definitions.yml#License" 404: content: application/json: schema: - $ref: "#/definitions/ResourceNotFound" + $ref: "./api/definitions.yml#ResourceNotFound" /api/v1/libraries/: get: @@ -763,23 +772,23 @@ paths: tags: - "Uploads and audio content" parameters: - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Search" - - $ref: "#/parameters/Scope" + - $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: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/OwnedLibrary" + $ref: "./api/definitions.yml#OwnedLibrary" post: tags: - "Uploads and audio content" @@ -795,7 +804,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/OwnedLibraryCreate" + $ref: "./api/definitions.yml#OwnedLibraryCreate" /api/v1/libraries/{uuid}/: parameters: @@ -814,7 +823,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/OwnedLibrary" + $ref: "./api/definitions.yml#OwnedLibrary" post: summary: Update a library tags: @@ -824,13 +833,13 @@ paths: content: application/json: schema: - $ref: "#/definitions/OwnedLibraryCreate" + $ref: "./api/definitions.yml#OwnedLibraryCreate" responses: 201: content: application/json: schema: - $ref: "#/definitions/OwnedLibrary" + $ref: "./api/definitions.yml#OwnedLibrary" delete: summary: Delete a library and all associated uploads description: | @@ -848,14 +857,14 @@ paths: tags: - "Channels and subscriptions" parameters: - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Scope" - - $ref: "#/parameters/Search" - - $ref: "#/parameters/Tags" - - $ref: "#/parameters/Subscribed" - - $ref: "#/parameters/External" - - $ref: "#/parameters/ChannelOrdering" + - $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: @@ -863,13 +872,13 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/Channel" + $ref: "./api/definitions.yml#Channel" post: summary: Create a new channel tags: @@ -884,7 +893,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/ChannelCreate" + $ref: "./api/definitions.yml#ChannelCreate" /api/v1/channels/metadata-choices: summary: List metadata (locales, itunes categories) for creating and editing channels. @@ -950,7 +959,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/Channel" + $ref: "./api/definitions.yml#Channel" post: summary: Update a channel tags: @@ -960,13 +969,13 @@ paths: content: application/json: schema: - $ref: "#/definitions/ChannelUpdate" + $ref: "./api/definitions.yml#ChannelUpdate" responses: 201: content: application/json: schema: - $ref: "#/definitions/Channel" + $ref: "./api/definitions.yml#Channel" delete: summary: Delete a channel and all associated uploads description: | @@ -1000,7 +1009,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/Subscription" + $ref: "./api/definitions.yml#Subscription" /api/v1/channels/{uuid}/rss/: parameters: @@ -1036,7 +1045,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/Subscription" + $ref: "./api/definitions.yml#Subscription" /api/v1/channels/{uuid}/unsubscribe/: parameters: @@ -1060,23 +1069,23 @@ paths: - "Uploads and audio content" parameters: - - $ref: "#/parameters/Search" - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Scope" + - $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: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/OwnedUpload" + $ref: "./api/definitions.yml#OwnedUpload" post: tags: - "Uploads and audio content" @@ -1117,7 +1126,7 @@ paths: - "pending" import_metadata: required: false - $ref: "#/definitions/ImportMetadata" + $ref: "./api/definitions.yml#ImportMetadata" /api/v1/subscriptions/{uuid}/: @@ -1137,7 +1146,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/Subscription" + $ref: "./api/definitions.yml#Subscription" /api/v1/subscriptions/: get: @@ -1150,13 +1159,13 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/Subscription" + $ref: "./api/definitions.yml#Subscription" /api/v1/subscriptions/all/: get: @@ -1173,7 +1182,7 @@ paths: results: type: "array" items: - $ref: "#/definitions/SubscriptionsAll" + $ref: "./api/definitions.yml#SubscriptionsAll" /api/v1/uploads/{uuid}/: parameters: @@ -1192,7 +1201,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/OwnedUpload" + $ref: "./api/definitions.yml#OwnedUpload" patch: summary: Update a draft upload description: | @@ -1210,7 +1219,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/OwnedUpload" + $ref: "./api/definitions.yml#OwnedUpload" delete: summary: Delete an upload description: | @@ -1247,10 +1256,10 @@ paths: tags: - "Content curation" parameters: - - $ref: "#/parameters/Search" - - $ref: "#/parameters/PageNumber" - - $ref: "#/parameters/PageSize" - - $ref: "#/parameters/Scope" + - $ref: "./api/parameters.yml#Search" + - $ref: "./api/parameters.yml#PageNumber" + - $ref: "./api/parameters.yml#PageSize" + - $ref: "./api/parameters.yml#Scope" responses: 200: @@ -1258,13 +1267,13 @@ paths: application/json: schema: allOf: - - $ref: "#/definitions/ResultPage" + - $ref: "./api/definitions.yml#ResultPage" - type: "object" properties: results: type: "array" items: - $ref: "#/definitions/TrackFavorite" + $ref: "./api/definitions.yml#TrackFavorite" post: summary: Mark the given track as favorite tags: @@ -1296,7 +1305,7 @@ paths: format: "int64" example: 98 creation_date: - $ref: "#/properties/creation_date" + $ref: "./api/properties.yml#creation_date" /api/v1/favorites/tracks/remove/: post: summary: Remove the given track from favorites @@ -1356,7 +1365,7 @@ paths: content: application/json: schema: - $ref: "#/definitions/Attachment" + $ref: "./api/definitions.yml#Attachment" delete: summary: Delete an attachment tags: @@ -1364,128 +1373,199 @@ paths: responses: 204: $ref: "#/responses/204" - -parameters: - - ChannelOrdering: - - $ref: "#/parameters/Ordering" - - default: "-creation_date" - schema: - required: false - type: "string" - example: "-creation_date" - enum: - - creation_date - - artist__modification_date - - External: - name: "external" - in: "query" - default: null - description: "Filter/exclude channels created from a third-party, non-Funkwhale RSS feed" - schema: - required: false - type: "boolean" - - - 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 to a given user or pod: - - Use `all` (or do not specify the property to disable scope filtering) - - Use `me` to retrieve content relative to the current user - - Use `actor:alice@example.com` to retrieve content relative to the account `alice@example.com - - Use `domain:example.com` to retrieve content relative to the domain `example.com - schema: - required: false - type: "string" - enum: - - "me" - - "all" - - "actor:alice@example.com" - - "domain:example.com" - - Search: - name: "q" - in: "query" - default: "all" - description: "Limit the results to the corresponding search query" - schema: - required: false - type: "string" - example: "Bonobo" - - Subscribed: - name: "subscribed" - in: "query" - description: "Limit or exclude results with a matching subsription from the current user" - schema: - required: false - type: boolean - - Tags: - name: "tag" - in: "query" - description: "Limit the results to the corresponding tags. May be used multiple times, to retrieve objects matching al provided tags" - schema: - required: false - type: array - collectionFormat: csv - example: - - rock - - metal - + /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}/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: responses: 200: description: Success @@ -1495,924 +1575,3 @@ responses: description: Successfully deleted 400: description: Bad request - -properties: - description: - type: object - description: Text content associated with another resource, like and artist or channel. - properties: - text: - type: string - example: "This is **me**" - description: "The raw user input" - content_type: - type: string - enum: - - text/markdown - - text/plain - - text/html - description: "The raw user input" - html: - type: string - description: "HTML output based on user input" - readOnly: true - - 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" - - content_category: - type: "string" - description: Used to what kind of content is published in a chanel - enum: - - music - - podcast - - other - - - -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 - - ChannelMetadata: - type: "object" - properties: - itunes_category: - type: string - example: Comedy - description: Itunes category (see `/api/v1/channels/metadata-choices`) for allowed values - itunes_subcategory: - type: string - example: Improv - description: Itunes subcategory (see `/api/v1/channels/metadata-choices`) for allowed values - language: - type: string - example: en - description: Language of the content, in ISO 639 format (see `/api/v1/channels/metadata-choices`) for allowed values - owner_name: - type: string - example: "Alice" - description: Used to make the channel compatible with other platforms (iTunes, Spotify, etc.) - owner_email: - type: string - example: "alice@example.com" - description: Used to make the channel compatible with other platforms (iTunes, Spotify, etc.) - - 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." - description: - $ref: "#/properties/description" - tags: - $ref: "#/properties/tags" - content_category: - $ref: "#/properties/content_category" - cover: - type: string - format: uuid - metadata: - $ref: "#/definitions/ChannelMetadata" - ChannelUpdate: - type: "object" - properties: - name: - type: "string" - example: "A short, public name for the channel" - maxLength: 255 - description: - $ref: "#/properties/description" - tags: - $ref: "#/properties/tags" - cover: - type: string - format: uuid - metadata: - $ref: "#/definitions/ChannelMetadata" - - 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 - - Subscription: - type: "object" - properties: - approved: - type: "string" - fid: - $ref: "#/properties/fid" - uuid: - type: "string" - format: "uuid" - creation_date: - $ref: "#/properties/creation_date" - channel: - $ref: "#/definitions/Channel" - - SubscriptionsAll: - type: "object" - properties: - uuid: - type: "string" - format: "uuid" - channel: - type: "string" - format: "uuid" - - 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 remaining will return to its higher possible value - reset_seconds: - type: "integer" - format: "int64" - example: 86267 - description: How many seconds to wait before remaining 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."