Newer
Older
# Undocumented endpoints:
# /api/v1/settings
# /api/v1/activity
# /api/v1/playlists
# /api/v1/playlist-tracks
# /api/v1/search
# /api/v1/radios
# /api/v1/history
description: |
Interactive documentation for [Funkwhale](https://funkwhale.audio) API.
The API is **not** freezed yet, but we will document breaking changes in our changelog,
and try to avoid those as much as possible.
Usage
-----
Click on an endpoint name to inspect its properties, parameters and responses.
Use the "Try it out" button to send a real world payload to the endpoint and inspect
the corresponding response.
Authentication
--------------
To authenticate, use the `/token/` endpoint with a username and password, and copy/paste
the resulting JWT token in the `Authorize` modal. All subsequent requests made via the interactive
documentation will be authenticated.
If you keep the default server (https://demo.funkwhale.audio), the default username and password
couple is "demo" and "demo".
Resources
---------
For more targeted guides regarding API usage, and especially authentication, please
refer to [https://docs.funkwhale.audio/api.html](https://docs.funkwhale.audio/api.html)
version: "1.0.0"
title: "Funkwhale API"
servers:
- url: https://demo.funkwhale.audio
- url: https://{domain}
description: Custom server
variables:
domain:
default: yourdomain
description: Your Funkwhale Domain
protocol:
enum:
- 'http'
- 'https'
default: 'https'
oauth2:
type: oauth2
description: This API uses OAuth 2 with the Authorization Code flow. You can register an app using the /oauth/apps/ endpoint.
flows:
authorizationCode:
# Swagger doesn't support relative URLs yet (cf https://github.com/swagger-api/swagger-ui/pull/5244)
authorizationUrl: /authorize
tokenUrl: /api/v1/oauth/token/
refreshUrl: /api/v1/oauth/token/
scopes:
"read": "Read-only access to all user data"
"write": "Write-only access on all user data"
"read:profile": "Read-only access to profile data"
"read:libraries": "Read-only access to library and uploads"
"read:playlists": "Read-only access to playlists"
"read:listenings": "Read-only access to listening history"
"read:favorites": "Read-only access to favorites"
"read:radios": "Read-only access to radios"
"read:edits": "Read-only access to edits"
"read:notifications": "Read-only access to notifications"
"read:follows": "Read-only to follows"
"read:filters": "Read-only to to content filters"
"write:profile": "Write-only access to profile data"
"write:libraries": "Write-only access to libraries"
"write:playlists": "Write-only access to playlists"
"write:follows": "Write-only access to follows"
"write:favorites": "Write-only access to favorits"
"write:notifications": "Write-only access to notifications"
"write:radios": "Write-only access to radios"
"write:edits": "Write-only access to edits"
"write:filters": "Write-only access to content-filters"
"write:listenings": "Write-only access to listening history"
jwt:
type: http
scheme: bearer
bearerFormat: JWT
description: "You can get a token by using the /token endpoint"
security:
- jwt: []
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
- name: Content curation
description: Favorites, playlists, radios
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
/api/v1/oauth/apps/:
post:
tags:
- "auth"
description:
Register an OAuth application
security: []
responses:
201:
content:
application/json:
schema:
allOf:
- $ref: "#/definitions/OAuthApplication"
- $ref: "#/definitions/OAuthApplicationCreation"
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
name:
type: "string"
example: "My Awesome Funkwhale Client"
summary: "A human readable name for your app"
redirect_uris:
type: "string"
example: "https://myapp/oauth2/funkwhale"
summary: "A list of redirect uris, separated by spaces"
scopes:
type: "string"
summary: "A list of scopes requested by your app, separated by spaces"
example: "read write:playlists write:favorites"
/api/v1/token/:
description:
Obtain a JWT token you can use for authenticating your next requests.
security: []
responses:
'200':
description: Successfull auth
'400':
description: Invalid credentials
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
username:
type: "string"
example: "demo"
password:
type: "string"
example: "demo"
/api/v1/auth/registration/:
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
post:
summary: Create an account
description: |
Register a new account on this instance. An invitation code will be required
if sign up is disabled.
tags:
- "Auth and security"
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
username:
type: "string"
example: "alice"
email:
type: "string"
format: "email"
invitation:
type: "string"
example: "INVITECODE"
required: false
description: An invitation code, required if signups are closed on the instance.
password1:
type: "string"
example: "passw0rd"
password2:
type: "string"
description: Must be identical to password1
example: "passw0rd"
responses:
201:
$ref: "#/responses/201"
/api/v1/auth/password/reset/:
post:
summary: Request a password reset
description: |
Request a password reset. An email with reset instructions will be sent to the provided email,
if it's associated with a user account.
tags:
- "Auth and security"
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
email:
type: "string"
format: "email"
responses:
200:
$ref: "#/responses/200"
/api/v1/users/users/me/:
get:
summary: Retrive profile information
description: |
Retrieve profile informations of the current user
tags:
- "Auth and security"
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/Me"
security:
- oauth2:
- "read:libraries"
parameters:
- name: "q"
in: "query"
description: "Search query used to filter artists"
schema:
required: false
type: "string"
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
- allOf:
- $ref: "#/parameters/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- id
- name
- $ref: "#/parameters/Playable"
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
responses:
200:
content:
application/json:
schema:
allOf:
- $ref: "#/definitions/ResultPage"
- type: "object"
properties:
results:
type: "array"
items:
$ref: "#/definitions/Artist"
/api/v1/artists/{id}/:
get:
summary: Retrieve a single artist
parameters:
- $ref: "#/parameters/ObjectId"
security:
- oauth2:
- "read:libraries"
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/Artist"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
/api/v1/artists/{id}/libraries/:
get:
summary: List available user libraries containing work from this artist
security:
- oauth2:
- "read:libraries"
parameters:
- $ref: "#/parameters/ObjectId"
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
tags:
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/LibraryPage"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
security:
- oauth2:
- "read:libraries"
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
parameters:
- name: "q"
in: "query"
default: null
description: "Search query used to filter albums"
schema:
required: false
type: "string"
- name: "artist"
in: "query"
default: null
description: "Only include albums by the requested artist"
schema:
required: false
type: "integer"
format: "int64"
- allOf:
- $ref: "#/parameters/Ordering"
- default: "-creation_date"
schema:
required: false
type: "string"
example: "creation_date"
enum:
- creation_date
- release_date
- title
- $ref: "#/parameters/Playable"
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
responses:
200:
content:
application/json:
schema:
allOf:
- $ref: "#/definitions/ResultPage"
- type: "object"
properties:
results:
type: "array"
items:
$ref: "#/definitions/Album"
get:
summary: Retrieve a single album
parameters:
- $ref: "#/parameters/ObjectId"
security:
- oauth2:
- "read:libraries"
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/Album"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
/api/v1/albums/{id}/libraries/:
get:
summary: List available user libraries containing tracks from this album
parameters:
- $ref: "#/parameters/ObjectId"
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
security:
- oauth2:
- "read:libraries"
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/LibraryPage"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
security:
- oauth2:
- "read:libraries"
parameters:
- name: "q"
in: "query"
default: null
description: "Search query used to filter tracks"
schema:
required: false
type: "string"
- name: "artist"
in: "query"
default: null
description: "Only include tracks by the requested artist"
schema:
required: false
type: "integer"
format: "int64"
- name: "favorites"
in: "query"
default: null
description: "filter/exclude tracks favorited by the current user"
schema:
required: false
type: "boolean"
- name: "album"
in: "query"
default: null
description: "Only include tracks from the requested album"
schema:
required: false
type: "integer"
format: "int64"
- name: "license"
description: "Only include tracks with the given license"
default: null
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"
security:
- oauth2:
- "read:libraries"
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/Track"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
/api/v1/tracks/{id}/libraries/:
get:
summary: List available user libraries containing given track
parameters:
- $ref: "#/parameters/ObjectId"
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
security:
- oauth2:
- "read:libraries"
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/LibraryPage"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
/api/v1/listen/{uuid}/:
get:
summary: Download the audio file matching the given track uuid
description: |
Given a track uuid (and not ID), return the first found audio file
accessible by the user making the request.
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
In case of a remote upload, this endpoint will fetch the audio file from the remote
and cache it before sending the response.
parameters:
- name: uuid
in: path
required: true
description: Track uuid
schema:
type: "string"
format: "uuid"
- name: to
in: query
required: false
description: |
If specified, the endpoint will return a transcoded version of the original
audio file.
Since transcoding happens on the fly, it can significantly increase response time,
and it's recommended to request transcoding only for files that are not playable
by the client.
This endpoint support bytess-range requests.
schema:
$ref: "#/properties/transcode_options"
- name: upload
in: query
required: false
summary: An upload uuid
description: |
If specified, will return the audio for the given upload uuid.
This is useful for tracks that have multiple uploads available.
schema:
type: string
format: uuid
tags:
- "Library and metadata"
responses:
200:
content:
'*/*':
description: "Audio file, as binary data"
schema:
type: string
format: binary
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
security:
- oauth2:
- "read:libraries"
parameters:
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
responses:
200:
content:
application/json:
schema:
allOf:
- $ref: "#/definitions/ResultPage"
- type: "object"
properties:
results:
type: "array"
items:
$ref: "#/definitions/License"
/api/v1/licenses/{code}/:
security:
- oauth2:
- "read:libraries"
parameters:
- name: code
in: path
description: License code
required: true
schema:
type: string
example: cc0-1.0
tags:
responses:
200:
content:
application/json:
schema:
$ref: "#/definitions/License"
404:
content:
application/json:
schema:
$ref: "#/definitions/ResourceNotFound"
/api/v1/libraries/:
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
get:
summary: List owned libraries
tags:
- "Uploads and audio content"
parameters:
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
responses:
200:
content:
application/json:
schema:
allOf:
- $ref: "#/definitions/ResultPage"
- type: "object"
properties:
results:
type: "array"
items:
$ref: "#/definitions/OwnedLibrary"
post:
tags:
- "Uploads and audio content"
description:
Create a new library
responses:
201:
$ref: "#/responses/201"
400:
$ref: "#/responses/400"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/definitions/OwnedLibraryCreate"
/api/v1/libraries/{uuid}/:
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
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:
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"
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
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
/api/v1/uploads/{uuid}/:
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
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"
/api/v1/favorites/tracks/:
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
get:
tags:
- "Content curation"
parameters:
- name: "q"
in: "query"
default: null
description: "Search query used to filter favorites"
schema:
required: false
type: "string"
- name: "user"
in: "query"
default: null
description: "Limit results to favorites belonging to the given user"
schema:
$ref: "#/parameters/ObjectId"
- $ref: "#/parameters/PageNumber"
- $ref: "#/parameters/PageSize"
responses:
200:
content:
application/json:
schema:
allOf:
- $ref: "#/definitions/ResultPage"
- type: "object"
properties:
results:
type: "array"
items:
$ref: "#/definitions/TrackFavorite"
post:
summary: Mark the given track as favorite
tags:
- "Content curation"
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
track:
type: "integer"
format: "int64"
example: 98
responses:
201:
content:
application/json:
schema:
type: "object"
properties:
id:
type: "integer"
format: "int64"
example: 876
track:
type: "integer"
format: "int64"
example: 98
creation_date:
$ref: "#/properties/creation_date"
/api/v1/favorites/tracks/remove/:
post:
summary: Remove the given track from favorites
tags:
- "Content curation"
requestBody:
required: true
content:
application/json:
schema:
type: "object"
properties:
track:
type: "integer"
format: "int64"
example: 98
responses:
204:
$ref: "#/responses/204"
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
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"
201:
description: Successfully created
204:
description: Successfully deleted
400:
description: Bad request
creation_date:
type: "string"
format: "date-time"
privacy_level:
type: string
example: "me"