Cookies and privacy

We use essential browser storage to remember your settings. With your permission, PostHog counts visits to our public pages. We do not track the app or sign-in pages, record sessions or collect form contents. Analytics stays off unless you accept. You can change your choice at any time.

Read about cookies and analytics

API reference

DisplayFlow’s REST API gives you programmatic access to screens, locations, media, playlists and schedules. All endpoints are JSON-based and authenticated via session cookies or API keys.

Base URL: https://displayflow.app Format: JSON Auth: Cookie or Bearer

Authentication

Manage sessions, organisations and API keys. Better Auth handles all authentication via /api/auth/*.

POST /api/auth/sign-up/email

Create account

Registers a new user with email and password. Sends a verification email.

Authentication: None

Parameters

email string Email address*
password string Password (min. 8 characters)*
name string Display name*

Code examples

curl -X POST https://displayflow.app/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"secret123","name":"Jane Smith"}'

Response

JSON 
{
  "user": {
    "id": "user_abc123",
    "email": "[email protected]",
    "name": "Jane Smith"
  },
  "session": { "id": "sess_xyz", "expiresAt": "..." }
}
POST /api/auth/sign-in/email

Sign in

Signs in with email and password. Returns a session via cookie.

Authentication: None

Parameters

email string Email address*
password string Password*

Code examples

curl -X POST https://displayflow.app/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"[email protected]","password":"secret123"}'

Response

JSON 
{
  "user": { "id": "user_abc123", "email": "[email protected]" },
  "session": { "id": "sess_xyz", "expiresAt": "..." }
}
GET /api/auth/get-session

Get session

Returns the current session and user if the cookie is valid.

Authentication: Session

Code examples

curl https://displayflow.app/api/auth/get-session \
  -b cookies.txt

Response

JSON 
{
  "user": { "id": "user_abc123", "email": "[email protected]" },
  "session": { "id": "sess_xyz", "expiresAt": "..." }
}
POST /api/auth/sign-out

Sign out

Invalidates the current session and clears the cookie.

Authentication: Session

Code examples

curl -X POST https://displayflow.app/api/auth/sign-out \
  -b cookies.txt

Screens

Manage physical and virtual screens. All endpoints are scoped to your organisation.

GET /api/screens

List screens

Retrieves all screens in your organisation. Accepts ?limit= and ?offset= (default 50, max 200).

Authentication: Session or API key

Parameters

limit number? Number of results (max 200)
offset number? Number of results to skip

Code examples

curl https://displayflow.app/api/screens?limit=50 \
  -H "Authorization: Bearer df_your_api_key"

Response

JSON 
[
  {
    "id": "screen_abc",
    "name": "Restaurant Screen 1",
    "status": "online",
    "platform": "browser",
    "locationId": "loc_xyz",
    "organizationId": "org_123",
    "lastSeenAt": "2026-08-03T11:00:00.000Z"
  }
]
POST /api/screens

Create screen

Creates a new screen in your organisation. Returns 201 on success.

Authentication: Session

Parameters

name string Screen name*
organizationId string Organisation ID*
platform string? Platform (browser, windows, android-tv, raspberry-pi, samsung-tizen, debian-usb)
locationId string? Location ID

Code examples

curl -X POST https://displayflow.app/api/screens \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"Lobby Screen","organizationId":"org_123","platform":"browser"}'

Response

JSON 
{
  "id": "screen_def",
  "name": "Lobby Screen",
  "status": "pending",
  "platform": "browser",
  "organizationId": "org_123"
}
GET /api/screens/:id

Get screen

Retrieves a specific screen. Returns 404 if the screen does not exist in your organisation.

Authentication: Session or API key

Code examples

curl https://displayflow.app/api/screens/screen_abc \
  -H "Authorization: Bearer df_your_api_key"
PATCH /api/screens/:id

Update screen

Updates a screen’s name, location or description.

Authentication: Session

Parameters

name string? New name
locationId string? New location
description string? Description

Code examples

curl -X PATCH https://displayflow.app/api/screens/screen_abc \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"Restaurant Screen 1"}'
DELETE /api/screens/:id

Delete screen

Permanently deletes a screen. Returns 204 on success.

Authentication: Session

Code examples

curl -X DELETE https://displayflow.app/api/screens/screen_abc \
  -b cookies.txt
POST /api/screens/:id/rotate-token

Rotate player token

Generates a new playerToken for the screen. Sends a reload signal to the connected device.

Authentication: Session

Code examples

curl -X POST https://displayflow.app/api/screens/screen_abc/rotate-token \
  -b cookies.txt

Locations

Manage locations to group screens physically or logically.

GET /api/locations

List locations

Retrieves all locations in your organisation.

Authentication: Session or API key

Code examples

curl https://displayflow.app/api/locations \
  -H "Authorization: Bearer df_your_api_key"

Response

JSON 
[
  {
    "id": "loc_xyz",
    "name": "Restaurant Stockholm",
    "slug": "restaurant-stockholm",
    "organizationId": "org_123"
  }
]
POST /api/locations

Create location

Creates a new location. The slug is generated automatically. Returns 201.

Authentication: Session

Parameters

name string Location name*
organizationId string Organisation ID*

Code examples

curl -X POST https://displayflow.app/api/locations \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"Restaurant Gothenburg","organizationId":"org_123"}'
DELETE /api/locations/:id

Delete location

Deletes a location. Screens at the location are left without a location. Returns 204.

Authentication: Session

Code examples

curl -X DELETE https://displayflow.app/api/locations/loc_xyz -b cookies.txt

Media

Manage the media library: images, video and documents. Supports presigned uploads to R2.

GET /api/media

List media

Retrieves all media files in your organisation.

Authentication: Session or API key

Code examples

curl https://displayflow.app/api/media -H "Authorization: Bearer df_your_api_key"

Response

JSON 
[
  {
    "id": "media_abc",
    "name": "summer-campaign.png",
    "type": "image",
    "status": "ready",
    "mimeType": "image/png",
    "size": 245678,
    "width": 1920,
    "height": 1080
  }
]
POST /api/media

Create media

Creates a media record. If R2 is configured, a presigned URL is returned for direct upload. Returns 201.

Authentication: Session

Parameters

name string File name*
type string image, video or document*
organizationId string Organisation ID*
mimeType string? MIME type (e.g. image/png)
size number? File size in bytes

Code examples

curl -X POST https://displayflow.app/api/media \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"name":"image.png","type":"image","organizationId":"org_123","mimeType":"image/png","size":245678}'

Response

JSON 
{
  "media": {
    "id": "media_abc",
    "name": "image.png",
    "status": "uploading"
  },
  "presignedUrl": "https://r2.example.com/upload?signature=..."
}
DELETE /api/media/:id

Delete media

Deletes a media file and all of its variants. Returns 204.

Authentication: Session

Code examples

curl -X DELETE https://displayflow.app/api/media/media_abc -b cookies.txt

Playlists

Manage playlists and their content. Playlists can contain images, video and documents.

GET /api/playlists

List playlists

Retrieves all playlists in your organisation.

Authentication: Session or API key

Code examples

curl https://displayflow.app/api/playlists -H "Authorization: Bearer df_your_api_key"

Response

JSON 
[
  {
    "id": "pl_abc",
    "name": "Lunch menu",
    "status": "active",
    "loop": true,
    "shuffle": false,
    "itemCount": 12
  }
]
POST /api/playlists

Create playlist

Creates a new playlist. Returns 201.

Authentication: Session

Parameters

name string Playlist name*
organizationId string Organisation ID*
description string? Description

Code examples

curl -X POST https://displayflow.app/api/playlists \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"name":"Evening menu","organizationId":"org_123"}'
DELETE /api/playlists/:id

Delete playlist

Deletes a playlist and all of its items. Returns 204.

Authentication: Session

Code examples

curl -X DELETE https://displayflow.app/api/playlists/pl_abc -b cookies.txt

Schedules

Manage scheduling — which playlists are shown on which screens, and when.

GET /api/schedules/playlist/:playlistId

Get schedule for playlist

Retrieves all schedule entries for a specific playlist, with screen names populated.

Authentication: Session or API key

Code examples

curl https://displayflow.app/api/schedules/playlist/pl_abc \
  -H "Authorization: Bearer df_your_api_key"

Response

JSON 
[
  {
    "id": "sched_abc",
    "screenId": "screen_abc",
    "screenName": "Restaurant Screen 1",
    "playlistId": "pl_abc",
    "dayOfWeek": 1,
    "startTime": "08:00",
    "endTime": "12:00"
  }
]
POST /api/schedules

Create schedule

Creates a new schedule entry. Returns 201.

Authentication: Session

Parameters

screenId string Screen ID*
playlistId string Playlist ID*
dayOfWeek number Day of the week (0=Sunday, 6=Saturday)*
startTime string Start time (HH:MM)*
endTime string End time (HH:MM)*

Code examples

curl -X POST https://displayflow.app/api/schedules \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"screenId":"screen_abc","playlistId":"pl_abc","dayOfWeek":1,"startTime":"08:00","endTime":"12:00"}'
DELETE /api/schedules/:id

Delete schedule

Deletes a schedule entry. Returns 204.

Authentication: Session

Code examples

curl -X DELETE https://displayflow.app/api/schedules/sched_abc -b cookies.txt

Pairing

Pair physical devices with screens using 6-digit codes.

POST /api/pairing/start

Start pairing

Generates a 6-digit code and a playerToken. The code is valid for 10 minutes.

Authentication: Session

Code examples

curl -X POST https://displayflow.app/api/pairing/start \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"organizationId":"org_123","screenId":"screen_abc"}'

Response

JSON 
{
  "code": "123456",
  "playerToken": "pt_xyz789",
  "expiresAt": "2026-08-03T11:10:00.000Z"
}
POST /api/pairing/check

Check pairing status

Checks whether a pairing code has been confirmed by a device.

Authentication: Session

Parameters

code string 6-digit pairing code*

Code examples

curl -X POST https://displayflow.app/api/pairing/check \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"code":"123456"}'

Billing

Manage subscriptions and plans via Stripe.

GET /api/billing/plans

List plans

Retrieves the available subscription plans. Public endpoint, no authentication required.

Authentication: None

Code examples

curl https://displayflow.app/api/billing/plans

Response

JSON 
{
  "starter": { "monthly": 23900, "yearly": 229000 },
  "pro": { "monthly": 59900, "yearly": 574000 }
}

Health

Monitor the API’s health and service status.

GET /api/health

Health check

Checks the status of the database, authentication, storage and billing. Public endpoint.

Authentication: None

Code examples

curl https://displayflow.app/api/health

Response

JSON 
{
  "status": "ok",
  "timestamp": "2026-08-03T11:00:00.000Z",
  "checks": {
    "database": { "status": "pass" },
    "auth": { "status": "pass" },
    "storage": { "status": "pass" },
    "billing": { "status": "pass" }
  }
}