On this page

API reference

This page is made from Starboard's API description, starboard/openapi.json (version 1.6.0), by tools/make_api_reference.py. It lists every address in version 1 of the API.

  • Every address starts with /api/v1 on your Starboard, such as http://192.168.1.20:8095/api/v1/apps.
  • Every request except the description itself needs a key, sent as Authorization: Bearer and the key. Addresses that change something are POST and need a key made with Read and manage. Read Authentication and keys.
  • The examples read the key from STARBOARD_KEY. Set it first, such as export STARBOARD_KEY=sb_read_....
  • Lists take limit and cursor, and every answer has an ETag. Read API quickstart.
  • Errors are problem details (RFC 9457), each explained in the list of API errors.
  • The same description is on your Starboard at /api/v1/openapi.json, for tools that read OpenAPI.

About

GET /api/v1/

The API's version, Starboard's version and links.

  • Key: any key.
  • Fresh for: 3600 seconds (Cache-Control: private, max-age=3600).
  • Operation id: getRoot.

The answer:

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/me

The key you are using: its name, right and scopes.

  • Key: any key.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: getMe.

The answer:

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/me"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/me",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/openapi.json

This description.

  • Key: none needed.
  • Operation id: getOpenApi.

The answer:

  • The OpenAPI 3.1 description.

Example:

curl -s "http://192.168.1.20:8095/api/v1/openapi.json"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/openapi.json")
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Apps

GET /api/v1/apps

The apps on the dashboard.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: listApps.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of App yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/apps"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/apps",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/apps/{id}

One app.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: getApp.

Parameters:

Name In What it is
id path text. Required.

The answer:

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/apps/sonarr"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/apps/sonarr",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/status

Whether each app answers, checked every 15 seconds at most.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 15 seconds (Cache-Control: private, max-age=15).
  • Operation id: listStatus.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/status"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/status",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/health

Problems the apps report.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 300 seconds (Cache-Control: private, max-age=300).
  • Operation id: listHealth.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes
errors a list of an object (its fields vary) no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/health"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/health",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/uptime

How long each app has answered, from the watch's checks.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: listUptime.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes
enabled true or false no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/uptime"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/uptime",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/app-updates

Updates that Sonarr, Radarr, Lidarr, Readarr and Prowlarr report.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 600 seconds (Cache-Control: private, max-age=600).
  • Operation id: listAppUpdates.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes
errors a list of an object (its fields vary) no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/app-updates"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/app-updates",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/numbers

Counts from each app, such as films, series and books.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: listNumbers.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/numbers"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/numbers",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/containers

Each app's container, its version and whether a newer image is out.

  • Key: any key whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: listContainers.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
available true or false yes
checked_at a number or null no
items a list of an object (its fields vary) yes
next_cursor text or null no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/containers"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/containers",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/containers/check

Check for newer images of the apps' containers now.

  • Key: a key made with Read and manage whose scopes are empty or include apps (your apps and their status). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: checkContainers.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
available true or false yes
checked_at a number or null no
items a list of an object (its fields vary) yes
next_cursor text or null no

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/containers/check"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/containers/check", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Downloads

GET /api/v1/downloads

What is downloading.

  • Key: any key whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Fresh for: 10 seconds (Cache-Control: private, max-age=10).
  • Operation id: listDownloads.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes
errors a list of an object (its fields vary) no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/downloads"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/downloads",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/transfer

Download speeds from each download app, and whether the VPN is connected.

  • Key: any key whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Fresh for: 5 seconds (Cache-Control: private, max-age=5).
  • Operation id: getTransfer.

The answer:

Field What it is Always there
clients a list of an object (its fields vary) yes
vpn a list of an object (its fields vary) yes
errors a list of an object (its fields vary) yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/transfer"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/transfer",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/download-hours

Download hours: whether they are active, and whether downloads run or wait now.

  • Key: any key whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Fresh for: 30 seconds (Cache-Control: private, max-age=30).
  • Operation id: getDownloadHours.

The answer:

Field What it is Always there
enabled true or false yes
start a whole number no
end a whole number no
mode one of run, pause no
reason text no
next_change text no
clients a list of text no
now a list of an object (its fields vary) no
errors a list of an object (its fields vary) no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/download-hours"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/download-hours",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/download-hours

Resume or pause downloads until the next change of the hours, or follow the hours again.

  • Key: a key made with Read and manage whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: actOnDownloadHours.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
enabled true or false yes
start a whole number no
end a whole number no
mode one of run, pause no
reason text no
next_change text no
clients a list of text no
now a list of an object (its fields vary) no
errors a list of an object (its fields vary) no

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{"action": "resume"}' "http://192.168.1.20:8095/api/v1/download-hours"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/download-hours", method="POST", data=b'{"action": "resume"}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/downloads/actions

Remove, block, or block and search again for one download, as the Downloads page does.

  • Key: a key made with Read and manage whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: actOnDownload.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
ok true or false yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{"app_id": "example", "id": 1, "action": "remove"}' "http://192.168.1.20:8095/api/v1/downloads/actions"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/downloads/actions", method="POST", data=b'{"app_id": "example", "id": 1, "action": "remove"}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/history

Reelix's history: what was sent to download, added and failed, newest first.

  • Key: any key whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: listHistory.

Parameters:

Name In What it is
cursor query The next_cursor of the previous answer.
which query Which events; all if left out.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/history"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/history",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/downloads/issues

Every download that needs attention or failed, with its details, and as Markdown for an AI helper.

Each app's queue is asked once when you call this (at most every 10 seconds), never on a timer. markdown starts with a short prompt telling an AI helper what to do, then one section for each download. Keys, passwords, tokens, private addresses and full download addresses are taken out; paths are only those in media and download folders.

  • Key: any key whose scopes are empty or include downloads (downloads, download hours and history). A key without it gets 404 not_found.
  • Fresh for: 10 seconds (Cache-Control: private, max-age=10).
  • Operation id: listDownloadIssues.

The answer:

Field What it is Always there
generated_at text (date-time) yes
count a whole number yes
apps_asked a whole number yes
items a list of DownloadIssue yes
errors a list of an object (its fields vary) yes
markdown text yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/downloads/issues"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/downloads/issues",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Media

GET /api/v1/recent

Recently added films, series and books.

  • Key: any key whose scopes are empty or include media (Coming up, recently added, what is playing and the Jellyfin jobs). A key without it gets 404 not_found.
  • Fresh for: 300 seconds (Cache-Control: private, max-age=300).
  • Operation id: listRecent.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/recent"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/recent",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/playing

What is playing in Jellyfin.

  • Key: any key whose scopes are empty or include media (Coming up, recently added, what is playing and the Jellyfin jobs). A key without it gets 404 not_found.
  • Fresh for: 20 seconds (Cache-Control: private, max-age=20).
  • Operation id: getPlaying.

The answer:

Field What it is Always there
configured true or false yes
items a list of an object (its fields vary) yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/playing"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/playing",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/calendar

Coming up: films, episodes, albums and books due, from the apps.

  • Key: any key whose scopes are empty or include media (Coming up, recently added, what is playing and the Jellyfin jobs). A key without it gets 404 not_found.
  • Fresh for: 600 seconds (Cache-Control: private, max-age=600).
  • Operation id: listCalendar.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.
month query A month, such as 2026-11, with a week either side. Without it, from yesterday for the days set in Settings, General.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes
errors a list of an object (its fields vary) no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/calendar"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/calendar",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/extras

Jellyfin and Audiobookshelf jobs: Live TV, watch history, user defaults and listening progress.

  • Key: any key whose scopes are empty or include media (Coming up, recently added, what is playing and the Jellyfin jobs). A key without it gets 404 not_found.
  • Fresh for: 30 seconds (Cache-Control: private, max-age=30).
  • Operation id: listExtras.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/extras"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/extras",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/extras/{name}/run

Run a Jellyfin or Audiobookshelf job now.

  • Key: a key made with Read and manage whose scopes are empty or include media (Coming up, recently added, what is playing and the Jellyfin jobs). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: runExtra.

Parameters:

Name In What it is
name path one of livetv, import, defaults, listening. Required.
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
accepted true or false yes
status text yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/extras/livetv/run"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/extras/livetv/run", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

System

GET /api/v1/system

Processor, memory, disks and uptime.

  • Key: any key whose scopes are empty or include system (processor, memory, disks and alerts). A key without it gets 404 not_found.
  • Fresh for: 10 seconds (Cache-Control: private, max-age=10).
  • Operation id: getSystem.

The answer:

Field What it is Always there
cpus a whole number no
load a list of a number no
memory an object (its fields vary) no
disks a list of an object (its fields vary) no
uptime_seconds a number no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/system"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/system",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/version

Starboard's version, and the newest release when checking for new versions is active.

  • Key: any key whose scopes are empty or include system (processor, memory, disks and alerts). A key without it gets 404 not_found.
  • Fresh for: 3600 seconds (Cache-Control: private, max-age=3600).
  • Operation id: getVersion.

The answer:

Field What it is Always there
current text yes
latest text or null no
repo text or null no
since a number or null no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/version"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/version",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/system/history

Processor, memory and network over the last hours.

  • Key: any key whose scopes are empty or include system (processor, memory, disks and alerts). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: getSystemHistory.

Parameters:

Name In What it is
hours query How many hours; 1 if left out.

The answer:

Field What it is Always there
hours a whole number yes
interval a whole number yes
points a list of an object (its fields vary) yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/system/history"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/system/history",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/alerts/test

Send a test alert to the channel set in Settings, Alerts.

  • Key: a key made with Read and manage whose scopes are empty or include system (processor, memory, disks and alerts). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: testAlert.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
ok true or false yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/alerts/test"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/alerts/test", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/logs

Starboard's log, newest first, with addresses, names and keys taken out.

Only for keys that ticked Logs: a key with no scopes does not read them.

  • Key: any key whose scopes include logs (the logs, only when ticked). A key without it gets 404 not_found.
  • Fresh for: 30 seconds (Cache-Control: private, max-age=30).
  • Operation id: listLogs.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.
level query problems for warnings and errors only; all if left out.
q query Only lines with these words.

The answer:

Field What it is Always there
items a list of an object yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/logs"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/logs",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/logs/limits

How long Starboard keeps its logs, the most they may take, and what they take now.

Only for keys that ticked Logs: a key with no scopes does not have them. Whichever limit comes first removes the oldest days: when a new day starts, when the limits change and when the size written passes the limit. They cover Starboard's own log (with its jobs, updates and plug-ins' lines), the API's audit log and the last Starboard update's log. apps is the apps' own limit, read from Docker.

  • Key: any key whose scopes include logs (the logs, only when ticked). A key without it gets 404 not_found.
  • Fresh for: 30 seconds (Cache-Control: private, max-age=30).
  • Operation id: getLogLimits.

The answer:

Field What it is Always there
keep_days one of 7, 14, 30, 60, 90, 180, 365 yes
max_mb one of 10, 25, 50, 100, 250, 500 yes
keep_days_choices a list of a whole number yes
max_mb_choices a list of a whole number yes
summary an object yes
covers a list of text yes
apps an object no
removed a whole number no
freed a whole number no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/logs/limits"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/logs/limits",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/logs/limits

Change how long Starboard keeps its logs and the most they may take.

Only for keys that ticked Logs: a key with no scopes does not have them. The same choices as Settings, General, Logs and feedback. Older days go at once; the answer says how many.

  • Key: a key made with Read and manage whose scopes include logs (the logs, only when ticked). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: setLogLimits.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
keep_days one of 7, 14, 30, 60, 90, 180, 365 yes
max_mb one of 10, 25, 50, 100, 250, 500 yes
keep_days_choices a list of a whole number yes
max_mb_choices a list of a whole number yes
summary an object yes
covers a list of text yes
apps an object no
removed a whole number no
freed a whole number no

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/logs/limits"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/logs/limits", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/logs/delete

Delete all logs.

Only for keys that ticked Logs: a key with no scopes does not have them. Every log the limits cover goes, apart from today's file and the audit log, which are emptied, and the last update's log while an update runs. Cannot be undone. The first new line says the key deleted them; this write is in the audit log too. The apps' own logs (Docker's) are not touched.

  • Key: a key made with Read and manage whose scopes include logs (the logs, only when ticked). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: deleteLogs.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
removed a whole number yes
emptied a whole number yes
freed a whole number yes
summary an object yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{"confirm": "example"}' "http://192.168.1.20:8095/api/v1/logs/delete"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/logs/delete", method="POST", data=b'{"confirm": "example"}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/backup/copies

Where copies of full backups go off this computer, the last copy and the last Test connection.

Never a password, key or rclone config: only whether the place is set up and where.

  • Key: any key whose scopes are empty or include system (processor, memory, disks and alerts). A key without it gets 404 not_found.
  • Fresh for: 30 seconds (Cache-Control: private, max-age=30).
  • Operation id: getBackupCopies.

The answer:

Field What it is Always there
kind one of off, disk, smb, nfs, rclone yes
where text no
where_words text no
service text no
keep a whole number no
status an object (its fields vary) no
tested an object or null no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/backup/copies"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/backup/copies",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/backup/copies/test

Test connection: reach the place, write a small file, read it back, remove it and check the room, as the page's button does.

  • Key: a key made with Read and manage whose scopes are empty or include system (processor, memory, disks and alerts). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: testBackupCopies.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
ok true or false yes
tested an object or null yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/backup/copies/test"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/backup/copies/test", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Requests

GET /api/v1/requests

Requests from Seerr or Reelix, newest first.

  • Key: any key whose scopes are empty or include requests (requests). A key without it gets 404 not_found.
  • Fresh for: 20 seconds (Cache-Control: private, max-age=20).
  • Operation id: listRequests.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.
pending query true for only those waiting for an answer.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes
configured true or false no
pending a whole number no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/requests"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/requests",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/requests/{id}/approve

Approve a request.

  • Key: a key made with Read and manage whose scopes are empty or include requests (requests). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: approveRequest.

Parameters:

Name In What it is
id path text. Required.
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
ok true or false yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/requests/123/approve"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/requests/123/approve", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/requests/{id}/decline

Decline a request, with an optional reason.

  • Key: a key made with Read and manage whose scopes are empty or include requests (requests). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: declineRequest.

Parameters:

Name In What it is
id path text. Required.
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
ok true or false yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/requests/123/decline"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/requests/123/decline", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Library

GET /api/v1/library

The Library: recently added, and how many there are on each tab.

  • Key: any key whose scopes are empty or include library (the Library). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: getLibrary.

The answer:

Field What it is Always there
recent a list of an object (its fields vary) yes
tabs a list of an object (its fields vary) yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/library"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/library",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/library/search

Search the Library: matches on each tab, best first.

  • Key: any key whose scopes are empty or include library (the Library). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: searchLibrary.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.
q query What to search for. Required.

The answer:

Field What it is Always there
items a list of an object (its fields vary) yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/library/search"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/library/search",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/library/status

How big each tab's index is, when it was built, and any error.

  • Key: any key whose scopes are empty or include library (the Library). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: getLibraryStatus.

The answer:

Field What it is Always there
tabs a list of an object (its fields vary) yes
errors an object (its fields vary) yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/library/status"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/library/status",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/library/refresh

Build one tab's index again, in the background.

  • Key: a key made with Read and manage whose scopes are empty or include library (the Library). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: refreshLibrary.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
accepted true or false yes
status text yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{"tab": "films"}' "http://192.168.1.20:8095/api/v1/library/refresh"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/library/refresh", method="POST", data=b'{"tab": "films"}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Events

GET /api/v1/events

Events as they happen, as Server-Sent Events.

A text/event-stream. Each event is CloudEvents-shaped JSON: specversion, id, type (such as starboard.app.down), source, time and data. A key hears only the events its scopes cover. Send Last-Event-ID to resume. Up to 8 streams at once; each closes after an hour.

  • Key: any key.
  • Operation id: streamEvents.

Parameters:

Name In What it is
Last-Event-ID header The id of the last event you read.

The answer:

  • The stream.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/events"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/events",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Updates

GET /api/v1/updates

What can be updated: Starboard, Reelix, the other apps and the plug-ins.

Only for keys that ticked Updates: a key with no scopes does not have them. From what Starboard already knows (its release check, the last check for app updates and the catalogues it has read): nothing is fetched to answer. running is the update running now, if any.

  • Key: any key whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Fresh for: 30 seconds (Cache-Control: private, max-age=30).
  • Operation id: listUpdates.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of UpdateTarget yes
next_cursor text or null yes
running UpdateRun or null no

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/updates"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/updates

Start an update to the newest version Starboard knows.

Only for keys that ticked Updates: a key with no scopes does not have them. One update runs at a time. Each has the same backup, health check and way back as on the pages: Starboard runs update.sh; Reelix and the other apps keep their old image until the new one is healthy; a plug-in runs its before step, moves its settings, waits for its health check and goes back by itself if it fails. Never from an address: only the version Starboard already found.

  • Key: a key made with Read and manage whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: startUpdate.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
accepted true or false yes
run UpdateRun yes
status text yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{"target": "example"}' "http://192.168.1.20:8095/api/v1/updates"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates", method="POST", data=b'{"target": "example"}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/updates/rollback

Roll a plug-in back to the version kept before its last update.

Only for keys that ticked Updates: a key with no scopes does not have them. Only plug-ins keep the version before. Starboard and the apps go back by themselves when a new version does not answer, so for them this answers 409 cannot_update.

  • Key: a key made with Read and manage whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: rollBackUpdate.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
accepted true or false yes
run UpdateRun yes
status text yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{"target": "example"}' "http://192.168.1.20:8095/api/v1/updates/rollback"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates/rollback", method="POST", data=b'{"target": "example"}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/updates/runs

The last 20 updates and roll backs, newest first.

Only for keys that ticked Updates: a key with no scopes does not have them.

  • Key: any key whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Fresh for: 5 seconds (Cache-Control: private, max-age=5).
  • Operation id: listUpdateRuns.

Parameters:

Name In What it is
limit query How many to give back; 1 to 200, 50 if left out.
cursor query The next_cursor of the previous answer.

The answer:

Field What it is Always there
items a list of UpdateRun yes
next_cursor text or null yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/updates/runs"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates/runs",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/updates/runs/{id}

One update's progress, step by step, and how it ended.

Only for keys that ticked Updates: a key with no scopes does not have them. While Starboard itself updates it restarts: the answer may not come for about a minute.

  • Key: any key whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Fresh for: 2 seconds (Cache-Control: private, max-age=2).
  • Operation id: getUpdateRun.

Parameters:

Name In What it is
id path text. Required.

The answer:

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/updates/runs/0123456789ab"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates/runs/0123456789ab",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

GET /api/v1/updates/all

What Install all updates would do now, in order, and what is held back.

Only for keys that ticked Updates: a key with no scopes does not have them. items run one at a time, in this order: the other apps, Jellyfin's plug-ins, Starboard's plug-ins, Reelix, then Jellyfin restarts once (never while someone is watching), then Starboard last. held lists what always waits for you: a plug-in asking for new permissions or that comes as a zip file, a new major version, and anything Starboard cannot update here. Reads each waiting plug-in's new manifest from its catalogue (kept 10 minutes). count does not include Jellyfin's plug-ins, whose new versions only Jellyfin knows.

  • Key: any key whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Fresh for: 60 seconds (Cache-Control: private, max-age=60).
  • Operation id: planAllUpdates.

The answer:

Field What it is Always there
items a list of an object yes
held a list of an object yes
count a whole number yes

Other answers:

  • 304: Not changed since the ETag sent in If-None-Match.

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" "http://192.168.1.20:8095/api/v1/updates/all"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates/all",
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"]})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

POST /api/v1/updates/all

Install all updates: every waiting update as one batch.

Only for keys that ticked Updates: a key with no scopes does not have them. One at a time, never in parallel, each with its own backup, health check and way back. One that fails goes back by itself and the rest carry on. Answers 409 update_running while another update runs, and 409 cannot_update when nothing is waiting or everything waiting is held back.

  • Key: a key made with Read and manage whose scopes include updates (updates, only when ticked). A key without it gets 404 not_found.
  • Needs: manage. A read key gets 403 right_needed. Send a JSON body; Idempotency-Key makes a retry safe.
  • Operation id: startAllUpdates.

Parameters:

Name In What it is
Idempotency-Key header Send the same value again to get the first answer back without doing it twice. Kept for 24 hours.

The answer:

Field What it is Always there
accepted true or false yes
run UpdateRun yes
status text yes

Errors:

Example:

curl -s -H "Authorization: Bearer $STARBOARD_KEY" -X POST -H "Content-Type: application/json" -d '{}' "http://192.168.1.20:8095/api/v1/updates/all"
import json, os, urllib.request

req = urllib.request.Request("http://192.168.1.20:8095/api/v1/updates/all", method="POST", data=b'{}',
                             headers={"Authorization": "Bearer " + os.environ["STARBOARD_KEY"],
                                      "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=10) as r:
    print(json.load(r))

Objects

The named objects the answers use.

App

Field What it is Always there
id text yes
name text yes
type text yes
group text yes
enabled true or false yes
url text yes
api_key_set true or false yes

DownloadIssue

Field What it is Always there
app text yes
app_id text yes
app_type one of sonarr, radarr, lidarr, readarr, reelix yes
reelix true or false yes
kind text yes
what text yes
title text yes
status one of Needs attention, Failed yes
app_state an object (its fields vary) yes
messages a list of text yes
size a number yes
progress a number yes
time_left text yes
added text yes
age text yes
indexer text yes
protocol text yes
quality text yes
download_client text yes
download_client_ids an object (its fields vary) yes
paths an object (its fields vary) yes
ids an object (its fields vary) yes
can_manual_import true or false no
tried a list of an object yes

Key

Field What it is Always there
id text yes
name text yes
right one of read, manage yes
scopes a list from apps, downloads, media, system, library, requests, logs, updates yes
created_at text (date-time) yes
expires_at text (date-time) or null no
last_used_at text (date-time) or null no
prefix text yes

Root

Field What it is Always there
api_version text yes
starboard_version text yes
links an object (its fields vary) yes

UpdateRun

Field What it is Always there
id text yes
target text yes
kind one of starboard, reelix, app, plugin, jellyfin-plugins, batch yes
name text yes
action one of update, rollback yes
from text yes
to text yes
by text yes
state one of running, updated, up-to-date, went-back, rolled-back, refused, failed, some-updated yes
said text yes
started_at text (date-time) yes
finished_at text (date-time) or null no
steps a list of an object yes

UpdateTarget

Field What it is Always there
id text yes
kind one of starboard, reelix, app, plugin yes
name text yes
current text yes
latest text yes
update_available true or false yes
can_update true or false yes
why text no
can_roll_back true or false yes
roll_back_to text no
note text no
big_change true or false no

Find out more

This page on GitHub, where the help is written.