Querying the API

PostgREST-style filtering, embedding related records with select, and getting your own content back out.

The API is built on PostgREST, which is worth knowing because it explains the query syntax: you filter, select, and embed with query parameters rather than through one endpoint per question.

If you have not made a request yet, Get started goes from a token to content on a screen in five of them.

Authenticating

Send your API token in the Authorization header, prefixed with Token.

curl -H "Authorization: Token $API_TOKEN" \
     https://api.screenlyapp.com/api/v4.1/assets

The examples below drop the host and write paths as /v4.1/....

Filtering

Comparisons go in the query string, as field=operator.value.

# every video
GET /v4.1/assets?type=eq.video

# playlists created since September 1, 2026
GET /v4.1/playlists?created_at=gte.2026-09-01

A filter value has to be one the field accepts, or the request returns an error. Label type is an example: it takes all-screens, manual, or screen. To find a label such as Landscape, filter by its name rather than its type.

# labels you created yourself
GET /v4.1/labels?type=eq.manual

Embedding related records

select decides which columns come back, and pulls in related tables in the same request.

# playlists, each with its items
GET /v4.1/playlists?select=*,playlist_items(*)

That is usually the difference between one request and a hundred: ask for the nested data rather than looping over ids.

Getting your content out

Every asset carries a source_url. Listing your assets and fetching each source_url is how you export a library.

The full reference

Endpoint by endpoint, with schemas, in the v4.1 API reference.