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/v1on your Starboard, such ashttp://192.168.1.20:8095/api/v1/apps. - Every request except the description itself needs a key, sent as
Authorization: Bearerand the key. Addresses that change something arePOSTand need a key made with Read and manage. Read Authentication and keys. - The examples read the key from
STARBOARD_KEY. Set it first, such asexport STARBOARD_KEY=sb_read_.... - Lists take
limitandcursor, and every answer has anETag. 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:
- Root.
Other answers:
- 304: Not changed since the ETag sent in If-None-Match.
Errors:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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:
- Key.
Other answers:
- 304: Not changed since the ETag sent in If-None-Match.
Errors:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- App.
Other answers:
- 304: Not changed since the ETag sent in If-None-Match.
Errors:
- 401:
key_needed. - 404:
not_found. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 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:
- 400:
bad_request. - 401:
key_needed. - 409:
not_set_up. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 409:
not_set_up. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 413:
too_large. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 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:
- 401:
key_needed. - 409:
not_set_up. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 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:
- 400:
bad_request. - 401:
key_needed. - 409:
not_set_up. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 409:
not_set_up. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited. - 503:
too_many_streams.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 409:
update_running,cannot_update. - 413:
too_large. - 429:
too_many_attempts,rate_limited. - 502:
app_failed.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 409:
update_running,cannot_update. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 400:
bad_request, whenlimitorcursoris wrong. - 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 404:
not_found. - 429:
too_many_attempts,rate_limited.
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 gets404 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:
- 401:
key_needed. - 429:
too_many_attempts,rate_limited.
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 gets404 not_found. - Needs:
manage. A read key gets403 right_needed. Send a JSON body;Idempotency-Keymakes 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:
- 400:
bad_request. - 401:
key_needed. - 403:
right_needed. - 404:
not_found. - 409:
update_running,cannot_update. - 413:
too_large. - 429:
too_many_attempts,rate_limited.
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.