Applications - Sunshine

These endpoints allow you to manage the applications available for streaming.

GET /api/apps

Get the list of available applications.

Authentication

Required

Response

apps

array

Array of application objects

name

string

Application name

cmd

string

Command to launch the application

output

string

Path to log output file (optional)

image-path

string

Full path to the application cover image (PNG file) (optional)

exclude-global-prep-cmd

boolean

Whether to exclude global preparation commands

elevated

boolean

Whether to run the application with elevated privileges

auto-detach

boolean

Whether to automatically detach from the application process

wait-all

boolean

Whether to wait for all child processes to exit

exit-timeout

integer

Timeout in seconds before force-closing the application

prep-cmd

array

Array of preparation commands (optional)

string

Command to execute before launching the application

undo

string

Command to execute after closing the application

elevated

boolean

Whether to run this command with elevated privileges

detached

array

Array of detached commands to run alongside the application (optional)

Example Request

curl -u admin:password \
  https://localhost:47990/api/apps

Example Response

{
  "apps": [
    {
      "name": "Steam",
      "cmd": "steam -bigpicture",
      "output": "/var/log/sunshine/steam.log",
      "exclude-global-prep-cmd": false,
      "elevated": false,
      "auto-detach": true,
      "wait-all": true,
      "exit-timeout": 5,
      "image-path": "/home/user/.config/sunshine/covers/steam.png"
    }
  ]
}

POST /api/apps

Create a new application or update an existing one.

Authentication

Required

Request Body

name

string

required

Application name

cmd

string

Command to launch the application

index

integer

required

Application index. Use -1 to create a new application, or provide the existing index to update an application

output

string

Path to log output file

image-path

string

Full path to the application cover image (must be a PNG file)

exclude-global-prep-cmd

boolean

default:false

Exclude global preparation commands

elevated

boolean

default:false

Run with elevated privileges

auto-detach

boolean

default:true

Automatically detach from the application process

wait-all

boolean

default:true

Wait for all child processes to exit

exit-timeout

integer

default:5

Timeout in seconds before force-closing

prep-cmd

array

Array of preparation commands

string

Command to execute before launching

undo

string

Command to execute after closing

elevated

boolean

Run with elevated privileges

detached

array

Array of detached commands (strings) to run alongside the application

Response

status

boolean

Whether the operation was successful

Example Request

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Desktop",
    "cmd": "",
    "index": -1,
    "auto-detach": true,
    "exit-timeout": 5
  }' \
  https://localhost:47990/api/apps

Example Response

{
  "status": true
}

Notes

Applications are automatically sorted by name after creation or update
Empty prep-cmd and detached arrays are removed from the configuration
Use index -1 to create a new application; it will be added to the end of the list (before sorting)

POST /api/apps/close

Close the currently running application.

Authentication

Required

Request Headers

Content-Type: application/json

Response

status

boolean

Whether the operation was successful

Example Request

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://localhost:47990/api/apps/close

Example Response

{
  "status": true
}

Notes

This terminates the currently running application process
The request body can be empty JSON {} but the Content-Type header is required

DELETE /api/apps/

Delete an application by its index.

Authentication

Required

Path Parameters

index

integer

required

The zero-based index of the application to delete

Response

status

boolean

Whether the operation was successful

result

string

Success message indicating which application was deleted

Example Request

curl -X DELETE \
  -u admin:password \
  https://localhost:47990/api/apps/2

Example Response

{
  "status": true,
  "result": "application 2 deleted"
}

Error Responses

If the index is out of range:

{
  "status_code": 400,
  "status": false,
  "error": "'index' 2 out of range, max index is 1"
}

If no applications exist:

{
  "status_code": 400,
  "status": false,
  "error": "No applications found"
}

GET /api/covers/

Get the cover image for an application.

Authentication

Required

Path Parameters

index

integer

required

The zero-based index of the application

Response

Returns the PNG image file with Content-Type: image/png header.

Example Request

curl -u admin:password \
  -o cover.png \
  https://localhost:47990/api/covers/0

Error Responses

If the application has no cover image:

{
  "status_code": 404,
  "error": "Cover image not found"
}

If the index is out of range:

{
  "status_code": 400,
  "status": false,
  "error": "'index' 5 out of range, max index is 3"
}

Notes

Only PNG files are supported for cover images
The image path is validated to ensure it’s a valid PNG file
If no custom image is set, the default image path is used

POST /api/covers/upload

Upload or download a cover image for applications.

Authentication

Required

Request Body

key

string

required

Unique identifier for the cover image (e.g., igdb_<game_id>)

url

string

URL to download the image from (must be from images.igdb.com). If provided, the image will be downloaded

data

string

Base64-encoded image data. Used if url is not provided

Response

status

boolean

Whether the upload was successful

path

string

File path where the cover image was saved

Example Request (URL)

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "key": "igdb_1234",
    "url": "https://images.igdb.com/igdb/image/upload/t_cover_big_2x/abc123.png"
  }' \
  https://localhost:47990/api/covers/upload

Example Request (Base64)

curl -X POST \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{
    "key": "my_custom_app",
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }' \
  https://localhost:47990/api/covers/upload

Example Response

{
  "status": true,
  "path": "/home/user/.config/sunshine/covers/igdb_1234.png"
}

Error Responses

If the key is missing:

{
  "status_code": 400,
  "status": false,
  "error": "Cover key is required"
}

If the URL host is not allowed:

{
  "status_code": 400,
  "status": false,
  "error": "Only images.igdb.com is allowed"
}

If the download fails:

{
  "status_code": 400,
  "status": false,
  "error": "Failed to download cover"
}

Notes

Images are stored in the covers/ subdirectory of the Sunshine config directory
The key is URL-escaped before being used as the filename
Only images.igdb.com is allowed as an external image source for security
You can use either url (for downloading) or data (for direct upload)

REST API

​GET /api/apps

​Authentication

​Response

​Example Request

​Example Response

​POST /api/apps

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Notes

​POST /api/apps/close

​Authentication

​Request Headers

​Response

​Example Request

​Example Response

​Notes

​DELETE /api/apps/

​Authentication

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​GET /api/covers/

​Authentication

​Path Parameters

​Response

​Example Request

​Error Responses

​Notes

​POST /api/covers/upload

​Authentication

​Request Body

​Response

​Example Request (URL)

​Example Request (Base64)

​Example Response

​Error Responses

​Notes

Build docs developers (and LLMs) love

GET /api/apps

Authentication

Response

Example Request

Example Response

POST /api/apps

Authentication

Request Body

Response

Example Request

Example Response

Notes

POST /api/apps/close

Authentication

Request Headers

Response

Example Request

Example Response

Notes

DELETE /api/apps/

Authentication

Path Parameters

Response

Example Request

Example Response

Error Responses

GET /api/covers/

Authentication

Path Parameters

Response

Example Request

Error Responses

Notes

POST /api/covers/upload

Authentication

Request Body

Response

Example Request (URL)

Example Request (Base64)

Example Response

Error Responses

Notes