You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
petitminion 50f002fa73 Create an scan Library celery task 4 days ago
..
compose/django Allow running docker container as non-root 8 months ago
config Create an scan Library celery task 4 days ago
funkwhale_api Create an scan Library celery task 4 days ago
tests Fixes broken channel page 3 weeks ago
.coveragerc Initial commit that merge both the front end and the API in the same repository 5 years ago
.dockerignore Docker setup is officialy documented! ❤️ 5 years ago
.pylintrc Initial commit that merge both the front end and the API in the same repository 5 years ago
Dockerfile Do not install pip as system package to avoid dependency clash 3 months ago
Readme.md Generate swagger 4 months ago
install_os_dependencies.sh See #542: ensure install_os_dependencies.sh is runnable from anywhere 4 years ago
manage.py Server CLI: user management 3 years ago
poetry.lock Update dependency requests-http-message-signatures to v0.3.1 (develop) 2 weeks ago
pyproject.toml Update dependency requests-http-message-signatures to v0.3.1 (develop) 2 weeks ago
requirements.pac Implement LDAP authentication 4 years ago
setup.cfg Fix #1105: Can now launch server import from the UI 2 years ago

Readme.md

Interactive documentation for Funkwhale API.

Backward compatibility between minor versions (1.X to 1.Y) is guaranteed for all the endpoints documented here.

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.

OAuth Authentication

You can register your own OAuth app using the /api/v1/oauth/apps/ endpoint. Proceed to the standard OAuth flow afterwards:

  • Our authorize URL is at /authorize
  • Our token acquisition and refresh URL is at /api/v1/oauth/token
  • The list of supported scopes is available by clicking the Authorize button in the Swagger UI documentation
  • Use urn:ietf:wg:oauth:2.0:oob as your redirect URI if you want the user to get a copy-pastable authorization code
  • At the moment, endpoints that deal with admin or moderator-level content are not accessible via OAuth, only through the Web UI

You can use our demo server at https://demo.funkwhale.audio for testing purposes.

Application token authentication

If using OAuth isn't practical and you have an account on the Funkwhale pod, you can create an application by visiting /settings.

Once the application is created, you can authenticate using its access token in the Authorization header, like this: Authorization: Bearer <token>.

Rate limiting

Depending on server configuration, pods running Funkwhale 0.20 and higher may rate-limit incoming requests to prevent abuse and improve the stability of service. Requests that are dropped because of rate-limiting receive a 429 HTTP response.

The limits themselves vary depending on:

  • The client: anonymous requests are subject to lower limits than authenticated requests
  • The operation being performed: Write and delete operations, as performed with DELETE, POST, PUT and PATCH HTTP methods are subject to lower limits

Those conditions are used to determine the scope of the request, which in turns determine the limit that is applied. For instance, authenticated POST requests are bound to the authenticated-create scope, with a default limit of 1000 requests/hour, but anonymous POST requests are bound to the anonymous-create scope, with a lower limit of 1000 requests/day.

A full list of scopes with their corresponding description, and the current usage data for the client performing the request is available via the /api/v1/rate-limit endpoint.

Additionally, we include HTTP headers on all API response to ensure API clients can understand:

  • what scope was bound to a given request
  • what is the corresponding limit
  • how much similar requests can be sent before being limited
  • and how much time they should wait if they have been limited
Rate limiting headers
Header Example value Description value
X-RateLimit-Limit 50 The number of allowed requests whithin a given period
X-RateLimit-Duration 3600 The time window, in seconds, during which those requests are accounted for.
X-RateLimit-Scope login The name of the scope as computed for the request
X-RateLimit-Remaining 42 How many requests can be sent with the same scope before the limit applies
Retry-After (if X-RateLimit-Remaining is 0) 3543 How many seconds to wait before a retry
X-RateLimit-Reset 1568126089 A timestamp indicating when X-RateLimit-Remaining will return to its higher possible value
X-RateLimit-ResetSeconds 3599 How many seconds to wait before X-RateLimit-Remaining returns to its higher possible value

Resources

For more targeted guides regarding API usage, and especially authentication, please refer to https://docs.funkwhale.audio/api.html