Skip to main content

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 tokenWith the scope
Deployment Manager at the organization that holds your clientsfleet: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

Scope: workspace:read

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agent-release" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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:

FieldUse it to
urlDownload the file.
sha256 and size_bytesCheck the download before it runs.
commandInstall 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:

PlaceholderFill 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

This example's token carries: workspace:readfleet:deploy

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/credential" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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

Scope: any of fleet:deployfleet:write

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

Request
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
{  "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

Scope: any of fleet:deployfleet:write

Request
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
Cache-Control: no-store
{  "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:

  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

Scope: workspace:read

Filter by registration_token_id, and page to the end.

Request
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
{  "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​

StepResponseCause and fix
Any403 with cause token_scopeThe token lacks fleet:deploy.
1404No agent version is published for your workspace's update ring. Contact support.
1502 APP_API_ERR_AGENT_RELEASE_UNAVAILABLEThe release could not be read or verified. Nothing is wrong with your request: try again later.
2200 with an empty listNo registration token you can see has that label. Create it.
2403 APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONThe 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.