Skip to main content

REST API overview

Who this is for​

The REST API runs anywhere your code can make an HTTP request: any platform, any language, client-side or server-side.

Choose the SDKs for the shortest path forward on Android, iOS and the web. Choose the API to reach any other platform, to run server-side, or to share one integration across every platform you support.

Calling the API directly makes your app responsible for retrieving and playing audio files, reporting every play, requesting skip permission before skipping a song, and managing client credentials.

Terminology​

These are the objects the API hands back, and the names it uses for them. A few will be familiar from elsewhere in these docs; the API gives some of them sharper edges.

  • Client. One installation or listener, identified by a client_id that you store and send with every request. Values longer than 23 characters are silently truncated; this only matters if you supply your own client id rather than using the one POST /session mints.
  • Session. What POST /session returns. It mints a client id on first call, identifies the latest placement, and reports whether the listener can play any music at all. The stations it returns are a subset of the placement's stations, enough to start playing without a second call, not the full list.
  • Station. A named group of music. A station carries two identifiers and they are not interchangeable. uuid is the stable one, and the only one an app should ever persist. id refers to a specific published instance of the station. A station may contain arbitrary customer JSON metadata (talk to your customer success partner to define these).
  • Placement. A versioned container that holds a collection of stations available to an app. Publishing new stations or changing station contents creates a new placement with all the new stations and changes, while the old placement keeps working and is unchanged. When making API calls, pass the placement_id returned with your session if you want to only work with stations and their contents as they were available at the time your session was started. Don't pass the placement_id if you want to search or interact with the latest version of any station (see GET /station vs GET /placement/{placement_id}/station). Using placement_id can free your app from having to worry about a station becoming unavailable or changing while your app runs.
  • Play. A reservation of one song, with a specific audio file URL and file encoding, for one client, created by POST /play call. A client repeatedly requests plays from the API servers and reports on their playback status ('started', 'elapsed', 'completed', 'invalidated', 'skipped').
  • Audio file. The transcoded file a play points at. It carries track, release and artist metadata plus a signed URL.

The spec, the reference, and an example client​

The OpenAPI document​

https://feed.fm/api/v3/openapi.yaml is the live document the server serves for itself. Point code generators and AI tooling at it. It needs no credentials.

If you are generating a client with an AI tool, start from the prompt on Generating code with an LLM. It tells the model to read the spec's prose, where a client's obligations are stated, in addition to the basic schema.

The API reference​

The API reference renders that same document for reading.

The example client​

feed-sample-client is a minimal browser client generated by Claude from the spec and the repo's PROMPT.md. Read it as a worked example of the call sequence, not a supported library. Do not take a dependency on it.

Versioning and changes​

The versioning and deprecation policy explains what counts as a breaking change, how long a deprecated version stays available, and how we notify you. The changelog records every change that affects integrations, newest first.