# Agent releases

The agent build to install: where to download each installer, how to check it, and the command that installs it.

- `GET /workspaces/{workspace_id}/agent-release` [Read the agent release](#read-agent-release)

## AgentRelease object

The SparkLogs Agent build a workspace's update ring publishes now, with its installers and their install commands. During a staged rollout, it is the build being rolled out.

- `ring` (one of the values below): The workspace's update ring, whose release this is.
  - `canary`: SparkLogs engineering's quality assurance ring.
  - `early_access`: Each version as soon as it is released.
  - `stable`: Each version after Early Access.
- `target` (one of the values below): The platform the installers are for.
  - `windows_x86_64`: Windows on x64.
- `version` (string): The agent version.
- `publisher` (string): The signer of both installers' Authenticode signature. Check it and the file's sha256 before running an installer.
- `installers` (array of AgentInstaller): The EXE, then the MSI.

## Read the agent release

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agent-release`

Preview

Returns the SparkLogs Agent build the workspace's update ring publishes now, which during a staged rollout is the build being rolled out: its version, the EXE and MSI with each file's URL, SHA-256 and size, the signer of their Authenticode signature, and a silent install command for each. Answered only once SparkLogs' signature on the release verifies. The commands hold placeholders, never a secret: `reveal-registration-token` reads the token.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `workspace.read`

Needs `workspace.read`. Any grant in the workspace carries `workspace.read`.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `ring`, `target`, `version`, `publisher`, `installers`

### Response (200)

- `agent_release` (AgentRelease, required): The agent release.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `workspace.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No build is published for the workspace's update ring. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 502 | `APP_API_ERR_AGENT_RELEASE_UNAVAILABLE` | The release could not be read, or its signature did not verify. | After `Retry-After` |
| 503 | `APP_API_ERR_NOT_CONFIGURED` | This server is not configured to read agent releases. | After `Retry-After` |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Example

Read the agent build to install and its install commands

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agent-release" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "agent_release": {
    "ring": "early_access",
    "target": "windows_x86_64",
    "version": "1.14.15",
    "publisher": "IT Lightning, LLC",
    "installers": [
      {
        "kind": "exe",
        "file_name": "SparkLogsAgentSetup-x64-1.14.15.exe",
        "url": "https://cdn.sparklogs.app/agent/data/1.14.15/windows_x86_64/sha256_5e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e7/SparkLogsAgentSetup-x64-1.14.15.exe",
        "sha256": "5e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e7",
        "size_bytes": 15556216,
        "command": "SparkLogsAgentSetup-x64-1.14.15.exe /qn /norestart EULA=ACCEPT REGISTRATION_TOKEN=\"<REGISTRATION_TOKEN>\" RMMCLIENTID=\"<RMMCLIENTID>\" PSACLIENTID=\"<PSACLIENTID>\" CLIENTNAME=\"<CLIENTNAME>\" RMMDEVICEID=\"<RMMDEVICEID>\" PSADEVICEID=\"<PSADEVICEID>\""
      },
      {
        "kind": "msi",
        "file_name": "SparkLogsAgent-x64-1.14.15.msi",
        "url": "https://cdn.sparklogs.app/agent/data/1.14.15/windows_x86_64/sha256_a9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1f/SparkLogsAgent-x64-1.14.15.msi",
        "sha256": "a9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1f",
        "size_bytes": 19189760,
        "command": "msiexec /i SparkLogsAgent-x64-1.14.15.msi /qn /norestart EULA=ACCEPT REGISTRATION_TOKEN=\"<REGISTRATION_TOKEN>\" RMMCLIENTID=\"<RMMCLIENTID>\" PSACLIENTID=\"<PSACLIENTID>\" CLIENTNAME=\"<CLIENTNAME>\" RMMDEVICEID=\"<RMMDEVICEID>\" PSADEVICEID=\"<PSADEVICEID>\" /l*v %TEMP%\\SparkLogsAgent-install.log"
      }
    ]
  },
  "message": "agent release retrieved"
}
```

## AgentInstaller object

- `kind` (one of the values below, required): Which installer it is.
  - `exe`: For an RMM or one machine.
  - `msi`: For Group Policy or Intune.
- `file_name` (string, required): The file's name, as the command names it.
- `url` (string, required): Where to download the file.
- `sha256` (string, required): The file's SHA-256, lowercase hex.
- `size_bytes` (integer, required): The file's size in bytes.
- `command` (string, required): A silent install command for cmd.exe, run from the file's folder. Replace each `<NAME>` with its value, writing a double quote inside a value twice. A parameter with no value is written `NAME=""` or removed whole, never as a bare `NAME=`. From PowerShell, pass the same arguments as the `-ArgumentList` array of `Start-Process`, each value inside its own double quotes and never the whole `NAME=value`: [https://sparklogs.com/docs/agents/deploy/cli](https://sparklogs.com/docs/agents/deploy/cli.md) has the script. The machine registers into the organization at or below the token's that records its `RMMCLIENTID` or `PSACLIENTID`, or a new one directly under the token's named `CLIENTNAME`; to register it into the token's own organization, leave out both ids and `CLIENTNAME` and add `USEPARENTORG=1`.

---

Source: <https://sparklogs.com/docs/api/reference/agent-releases>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
