# Fetch Latest Agent Installer

Most MSPs do not need the API to deploy agents.
The usual way is one RMM script with the installer URL and hash copied from [Deploy with your RMM](https://sparklogs.com/docs/agents/deploy/rmm.md).
An installed agent [updates itself](https://sparklogs.com/docs/agents/manage.md#how-automatic-updates-work), whichever version the script installed.
Update the URL and hash in the script periodically, and new installs start on a newer version.

Use the API for the installer in two less common cases:

- Your own tooling builds the deployment package, or you need to update your RMM deployment package automatically.
- Your RMM script looks up the installer each time it runs.

## What the token needs

| Give a workspace token | With the scope |
| - | - |
| **Deployment Manager** at the organization that holds your clients | `fleet:deploy` |

`fleet:deploy` is needed to read the registration token's secret in step 2.
Reading the installer alone takes any token for the workspace.

## Steps

### 1. Read the installer

**`GET /workspaces/{workspace_id}/agent-release`** [Read the agent release](https://sparklogs.com/docs/api/reference/agent-releases.md#read-agent-release)

Scope: `workspace:read`

```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"
}
```

The response lists the agent version your workspace installs today, as an EXE and an MSI.
Each installer has these fields:

| Field | Use it to |
| - | - |
| `url` | Download the file. |
| `sha256` and `size_bytes` | Check the download before it runs. |
| `command` | Install silently. |

Check that the file's Authenticode signer is the `publisher` in the response.
See [Download and verify](https://sparklogs.com/docs/agents/download-verify.md) for how.

`command` is written for the Windows command prompt (`cmd.exe`) and fails when pasted into PowerShell.
In PowerShell, use the script on [Deploy from the command line](https://sparklogs.com/docs/agents/deploy/cli.md), which passes the same properties as an array.

`command` has placeholders in angle brackets and holds no secret:

| Placeholder | Fill with |
| - | - |
| `<REGISTRATION_TOKEN>` | The registration token's secret, from step 2. |
| `<RMMCLIENTID>` or `<PSACLIENTID>` | The client's id in your RMM or PSA. At least one of the two is required. |
| `<CLIENTNAME>` | The client's name, used when the install creates the organization. |
| `<RMMDEVICEID>`, `<PSADEVICEID>` | Optional: the device's own id in your RMM or PSA. |

For a property you do not use, keep the quotes and leave the value empty, as in `RMMDEVICEID=""`, or remove the whole property.
Do not write a bare `RMMDEVICEID=` with nothing after it: the installer then takes the next argument as its value.
Write a double quote inside a value twice: `CLIENTNAME="Bob ""The Fixer"" IT"`.

### 2. Read the registration token's secret

One registration token at the organization that holds your clients serves every client.
Each install passes its client's RMM or PSA id, and SparkLogs places the device in that client's organization. An organization that does not exist yet is created.

**`GET /credential`** [Read credential metadata](https://sparklogs.com/docs/api/reference/credential.md#read-credential)

This example's token carries: `workspace:read`, `fleet:deploy`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/credential" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "credential": {
    "kind": "workspace_key",
    "credential_id": "4b1d0000-0000-4000-8000-000000000803",
    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
    "region_id": "us-central",
    "scope_restriction": "listed",
    "scopes": [
      "workspace:read",
      "fleet:deploy"
    ],
    "expires_at": "2027-11-10T09:00:00Z"
  },
  "message": "credential retrieved"
}
```

**`GET /workspaces/{workspace_id}/registration-tokens`** [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)

Scope: any of `fleet:deploy`, `fleet:write`

Filter by `label`. The match is exact, ignoring case.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?organization_id=0a9e0000-0000-4000-8000-000000000100&status=active&label=Northwind%20clients%20agents" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "as_of": "2026-11-10T09:01:00Z",
  "message": "registration tokens retrieved",
  "next_cursor": null,
  "registration_tokens": [
    {
      "id": "7e0c0000-0000-4000-8000-000000000303",
      "organization_id": "0a9e0000-0000-4000-8000-000000000100",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "7e0c0000-0000-4000-8000-000000000303"
      ],
      "label": "Northwind clients agents",
      "status": "active",
      "created_by_user_id": "AlexRiveraExampleUserId00001",
      "expires_at": null,
      "revoked_at": null,
      "revocation_reason": null,
      "use_count": 1,
      "last_used_at": "2026-11-04T09:00:00Z",
      "created_at": "2026-11-01T10:00:00Z",
      "updated_at": "2026-11-04T09:00:00Z",
      "deleted_at": null
    }
  ],
  "watermark": "2026-11-10T09:00:00Z"
}
```

**`GET /workspaces/{workspace_id}/registration-tokens/{id}/secret`** [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000303/secret" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "message": "registration token retrieved",
  "token": "EXAMPLE-CLIENTS-REGISTRATION-TOKEN-NOT-REAL"
}
```

Create the registration token once, in the app or with [create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token).
Later runs find the same registration token by its label.
Store the secret as a secret in your RMM.
Every read of the secret is recorded in the audit log.

A script that already holds the registration token's secret can skip this step.

### 3. Deploy with your RMM

This step is not an API call.
Your RMM, or your own tooling, does the following on each device:

1. Downloads the installer from `url`.
2. Checks the file against `sha256`.
3. Fills the placeholders in `command`.
4. Runs the command.

### 4. Confirm the devices registered

This step is optional.

**`GET /workspaces/{workspace_id}/agents`** [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)

Scope: `workspace:read`

Filter by `registration_token_id`, and page to the end.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents?registration_token_id=7e0c0000-0000-4000-8000-000000000303" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "agents": [
    {
      "id": "a9e70000-0000-4000-8000-000000000202",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "wb-pc-04",
      "organization_id": "0a9e0000-0000-4000-8000-000000000103",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000103",
        "a9e70000-0000-4000-8000-000000000202"
      ],
      "reported_state": "running",
      "agent_status": "online",
      "reported_state_changed_at": "2026-11-04T09:00:00Z",
      "collection_status": "behind",
      "stuck_reason": null,
      "last_data_at": "2026-11-10T14:00:00Z",
      "last_heartbeat_at": "2026-11-10T15:00:00Z",
      "host_class": "workstation",
      "reported_hostname": "wb-pc-04",
      "rmm_device_id": null,
      "psa_device_id": null,
      "agent_version": "1.14.4",
      "os_family": "windows",
      "os_version": "10.0.19045",
      "created_at": "2026-11-04T09:00:00Z",
      "updated_at": "2026-11-10T15:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    }
  ],
  "as_of": "2026-11-10T15:05:00Z",
  "message": "agents retrieved",
  "next_cursor": null
}
```

Each agent in the list is in the organization its client id named.
`agent_status` shows whether the agent is checking in, and `collection_status` shows whether it is collecting.
A device missing from the list did not register. Your RMM's job result has the reason the install failed.

## If a step fails

| Step | Response | Cause and fix |
| - | - | - |
| Any | 403 with `cause` `token_scope` | The token lacks `fleet:deploy`. |
| 1 | 404 | No agent version is published for your workspace's update ring. Contact support. |
| 1 | 502 `APP_API_ERR_AGENT_RELEASE_UNAVAILABLE` | The release could not be read or verified. Nothing is wrong with your request: try again later. |
| 2 | 200 with an empty list | No registration token you can see has that label. Create it. |
| 2 | 403 `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` | The token's role does not allow reading registration token secrets at that organization. |

## Idempotency (safety of repeated API calls)

Every call on this page is a read and is safe to repeat.

## What the API does not do

- It does not hand the command to your RMM or run it on a device.
- It does not report an install that failed before the device registered. Your RMM's job result shows that failure.

---

Source: <https://sparklogs.com/docs/api/use-cases/deploy-agents>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
