api

Call the signageOS REST API with the stored credentials and print the raw response

Description

Calls any signageOS REST API endpoint with the credentials stored by sos login and prints the raw response body to stdout. Built for scripts and AI agents that need endpoints the CLI has no dedicated command for: device search, telemetry, screenshots, debug settings, timings.

The path is always relative to the API URL, so it cannot change the host. --api-url and SOS_API_URL do change it, and the stored token is sent there. With an Auth0 login the default organization (or --organization-uid) is appended as the organizationUid query parameter; with legacy organization credentials it is omitted because the credentials already carry it.

GET is the default; POST, PUT and DELETE require --confirm-write per invocation. Review the target and body first: writes can permanently change data. The flag records opt-in, not proof of human approval; server permissions still apply.

Diagnostics go to stderr; stdout holds nothing but the response body. A non-2xx status is printed to stderr as HTTP <status> <text> and the exit code is 1.

Usage

sos api [options]

Options

Option	Description
--method	HTTP method: GET (default), POST, PUT or DELETE (string)
--path	API path relative to the API URL, query string allowed, e.g. /v2/device?limit=10 (string)
--data	JSON request body, inline or @path/to/file.json (string)
--confirm-write	Explicitly allow this POST, PUT or DELETE request; it may change or permanently delete data (boolean)
--organization-uid	Organization UID (string)
--no-default-organization	Prevent using the defaultOrganizationUid from ~/.sosrc (boolean)

Examples

# Search devices in the default organization
sos api --path "/v2/device?search=lobby&limit=20"

# Latest telemetry of one device
sos api --path /v1/device/<deviceUid>/telemetry/latest

# Ask a device for a fresh screenshot
sos api --method POST --confirm-write --path /v1/device/<deviceUid>/screenshot

# Create a timing from a JSON file (safest quoting on Windows)
sos api --method POST --confirm-write --path /v1/timing --data

## Advanced Usage

### Organization scope

| Login type | How the organization is chosen |
|---|---|
| `sos login` (Auth0) | `--organization-uid`, else `defaultOrganizationUid` from `~/.sosrc`, appended as `organizationUid=` query parameter |
| `SOS_API_IDENTIFICATION` + `SOS_API_SECURITY_TOKEN` | Carried by the credentials; no query parameter is sent |

Use `--no-default-organization` for account-level endpoints such as `/v1/organization`.

### Write safety

`GET` is the default. `POST`, `PUT` and `DELETE` require `--confirm-write` on each invocation and print the opt-in to stderr. Review the organization, target and body first: writes can change or permanently delete data. The flag is not proof of human approval or a substitute for server permissions. Use least-privilege credentials; agents must ask for explicit approval before supplying it.

### Request bodies

`--data` takes inline JSON or `@file.json` and is rejected for `GET`. On Windows prefer the file form: shells there mangle inline quotes.

```bash
echo '{"devicePowerAction":"APPLET_RELOAD"}' > action.json
sos api --method POST --confirm-write --path /v1/device/<deviceUid>/power-action --data @action.json

Git Bash on Windows

Git Bash rewrites arguments starting with / into Windows paths, so --path /v2/device arrives as C:/Program Files/Git/v2/device and is rejected. Disable the conversion for the call:

MSYS_NO_PATHCONV=1 sos api --path /v2/device

Reading the result

stdout is the response body only, so it can be piped to jq or parsed by a script. Progress, warnings and the update notice go to stderr. Exit code 1 means the API answered with a non-2xx status; the body is still printed.

Related commands

• sos device power-action - reboot, reload and other power actions without writing JSON
• sos device set-content - assign an applet with a default timing
• sos skill install - install the agent skill that uses this command

Since

4.5.0

Global Options

All commands support the following global options:

Option	Alias	Description
--help	-h	Display help information for any command
--version	-v	Display the installed version of the CLI
--api-url	-u	Override the API URL for REST requests
--profile		Use a specific profile from ~/.sosrc config

Examples

# Show version
sos --version

# Get help for any command
sos applet --help
sos applet upload --help

# Use custom API endpoint
sos --api-url https://api.example.com applet upload

# Use specific profile
sos --profile production organization list

See Also

• REST API reference