Applications

API endpoints for managing streaming applications

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)

do · 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

do · 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)