Something went wrong. Try again.
A decentralized music tracking and discovery platform built on AT Protocol 🎵 rocksky.app
Something went wrong. Try again.
3.8 kB · 118 lines
MDX
at main
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119---title: "Introduction"description: "The Rocksky HTTP API, built on AT Protocol XRPC."icon: "terminal"---
The Rocksky API is an XRPC ([AT Protocol](https://atproto.com)) API. Everyendpoint lives under the `app.rocksky.*` namespace and is reachable at`https://api.rocksky.app/xrpc/<nsid>`.
## Base URL
```https://api.rocksky.app```
## Authentication
Authenticated endpoints expect a **bearer token** in the `Authorization`header:
```Authorization: Bearer <your_jwt>```
You can obtain a token by:
- Signing in at [rocksky.app](https://rocksky.app) and copying the OAuth callback JWT- Running [`rocksky login <handle>`](/cli/login) with the CLI- Creating an [API key](/cli/create-apikey) for an application- Creating a personal **Access Token** at [rocksky.app/access-tokens](https://rocksky.app/access-tokens) — name it, copy the secret once, and use it interchangeably with a JWT (see [Personal access tokens](#personal-access-tokens) below)
Public profiles, charts, public scrobble feeds, and search work withoutauthentication. Private library, notification, and account operations requireauthentication even when they only read data. Some public endpoints accept atoken to include viewer-specific information. Each endpoint lists its ownauthentication requirements.
## Personal access tokens
Access tokens are long-lived JWTs you generate from the web UI for scripts,CLIs, and integrations that can't run an interactive OAuth flow. They behaveexactly like an OAuth-issued JWT — pass them in the `Authorization: Bearer`header on any authenticated endpoint.
Create / list / revoke them at:
- Web: [rocksky.app/access-tokens](https://rocksky.app/access-tokens)- Mobile web: [m.rocksky.app/access-tokens](https://m.rocksky.app/access-tokens)
The full secret is shown **once**, at creation — copy it somewhere safe.Subsequent listings only show the last four characters. Deleting a tokenrevokes it immediately on the API side (no waiting for expiry).
```httpGET https://api.rocksky.app/access-tokensAuthorization: Bearer <jwt-or-access-token>
POST https://api.rocksky.app/access-tokensAuthorization: Bearer <jwt-or-access-token>Content-Type: application/json
{ "name": "my-laptop" }
DELETE https://api.rocksky.app/access-tokens/{id}Authorization: Bearer <jwt-or-access-token>```
## Audioscrobbler endpoints
For Last.fm / ListenBrainz compatibility, Rocksky exposes a separate host:
```https://audioscrobbler.rocksky.app```
- [Migrate from Last.fm](/migrations/from-lastfm)- [Migrate from ListenBrainz](/migrations/from-listenbrainz)
## SDKs
Prefer typed bindings? Use one of the [official SDKs](/sdks/overview) inTypeScript, Python, Rust, Go, Ruby, Kotlin, Elixir, Clojure, or Gleam — everyendpoint in this reference is wrapped.
## Errors
Non-2xx responses return an XRPC-style error body:
```json{ "error": "InvalidRequest", "message": "actor must be a DID or handle"}```
The HTTP status code carries the category (400-class for client errors,500-class for server errors).
## OpenAPI spec
The endpoint reference below is generated directly from the[OpenAPI specification](/api-reference/openapi.json) shipped with this site.It follows the registered XRPC routes and lexicons in the Rocksky sourcerepository. Production may run an earlier revision.
Queries use `GET`; procedures use `POST`. Some procedures take query parametersinstead of a JSON body, so follow the parameter location shown on each endpoint.Nullable response fields are distinct from optional fields. OpenSubsonic payloadsretain provider-defined fields.
Routes whose handlers are unfinished are marked in the reference. Some handlersreturn empty fallback objects when an upstream service fails; HTTP 200 alonedoes not always mean that a lookup found data.