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. An installed agent updates itself, 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
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agent-release" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agent-release" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agent-release" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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 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, 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.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/credential" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/credential" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/credential" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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"}/workspaces/{workspace_id}/registration-tokens Scope: any of fleet:deployfleet:write
Filter by label. The match is exact, ignoring case.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "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" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "organization_id": "0a9e0000-0000-4000-8000-000000000100", "status": "active", "label": "Northwind clients agents", },)response.raise_for_status(){ "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"}/workspaces/{workspace_id}/registration-tokens/{id}/secret Scope: any of fleet:deployfleet:write
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000303/secret" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000303/secret" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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. 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:
- Downloads the installer from
url. - Checks the file against
sha256. - Fills the placeholders in
command. - Runs the command.
4. Confirm the devices registered
This step is optional.
/workspaces/{workspace_id}/agents Scope: workspace:read
Filter by registration_token_id, and page to the end.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents?registration_token_id=7e0c0000-0000-4000-8000-000000000303" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "registration_token_id": "7e0c0000-0000-4000-8000-000000000303", },)response.raise_for_status(){ "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.