Agents
An agent is a SparkLogs Agent on a machine; list them, read one, count them by enrollment, activity, contact and collection, and rename, move, delete or restore one.
Agents and ingest keys are separate: an ingest key's id names no agent here, and returns 404 to a read and 403 to a change, as an id that does not exist does.
An agent's name follows its machine's host name until someone sets a different name; to make it follow again, set the name to the current reported_hostname, in any case. To label an agent and keep its name following, use description.
Belongs to: Workspaces, Organizations, Registration tokens
- GET
List agents/workspaces /{workspace_id} /agents - GET
Read an agent/workspaces /{workspace_id} /agents /{id} - GET
Count agents/workspaces /{workspace_id} /agents /summary - PATCH
Update an agent/workspaces /{workspace_id} /agents /{id} - DELETE
Delete an agent/workspaces /{workspace_id} /agents /{id} - POST
Restore a deleted agent/workspaces /{workspace_id} /agents /{id} /restore - POST
Move an agent/workspaces /{workspace_id} /agents /{id} /move
Agent object
An agent is a SparkLogs Agent installed on a machine: it reports whether it is in contact and how its collection stands.
iduuidThe agent's id.
workspace_id uuidThe workspace the agent belongs to.
namestring or nullThe agent's name. It starts as the host name the agent registered with, as the machine spells it, and follows the host name until someone sets a different name: a check-in reporting a new host name renames the agent, which waits while two machines share the agent's identity. To make it follow again, set the name to the current reported_hostname, in any case. To label an agent and keep its name following the host name, use description.
organization_id uuidThe organization the agent belongs to.
patharray of uuid or nullThe organization ids from the top-level organization down to the agent's own, then the agent's id.
reported_state string or nullThe last service state the agent reported, such as running or stopped; unregistered until it first checks in. It is what the agent last said, not whether it is in contact now: a machine that lost power still shows running. agent_status says whether it is in contact. More values may be added.
agent_status one of the values belowWhether the agent is in contact, worked out from what it last announced and when anything last arrived from it: on a list at the page's as_of, the same instant for every page of one walk, and on a read of one agent when the response is written. It does not change updated_at. The same value the SparkLogs MCP server sends. It says nothing about collection: see collection_status. These are the values it takes today.
onlineThe agent checked in or sent data in the last 15 minutes.offlineNothing has arrived for longer than that, and the agent did not say it was stopping; the cause is unknown.never_seenEnrolled, and nothing has arrived from it yet.stoppedThe agent said its service was stopped.system_shutdownThe agent said its machine was shutting down.uninstalledThe agent said it was being uninstalled.upgrading_overdueThe agent said it was updating itself and has not come back after 30 minutes.deletedThe agent is deleted.
reported_state_changed_at date-time or nullWhen reported_state last changed.
collection_status string or nullSparkLogs' rollup of the agent's collection health across its feeds, worked out from what the agent last reported: healthy, behind, onboarding, degraded or unknown, and more values may be added. Null until first worked out; null and unknown never mean healthy.
stuck_reason string or nullWhy the agent is checking in but not collecting; null while it collects.
last_data_at date-time or nullWhen log data from the agent last arrived, recorded at most once every five minutes. It is legitimately old on a quiet, healthy machine. Null until data first arrives.
last_heartbeat_at date-time or nullWhen the agent last checked in, about every five minutes while it runs. Null until it first checks in.
host_class string or nullThe kind of machine the agent runs on: workstation or server today, and more values may be added.
reported_hostname string or nullThe host name the agent reported, in lower case.
rmm_device_id string or nullThe id your RMM uses for the agent's machine, as the installer was given it or as set later; null when none is recorded. Not unique, and it decides nothing about where the agent belongs or who may act on it.
psa_device_id string or nullThe id your PSA uses for the agent's machine, as the installer was given it or as set later; null when none is recorded. Not unique, and it decides nothing about where the agent belongs or who may act on it.
agent_version string or nullThe agent's version.
os_family string or nullThe operating system family the agent reported.
os_version string or nullThe operating system version the agent reported.
created_at date-timeWhen the agent was created.
updated_at date-timeWhen the agent's record last changed. Every check-in changes it, and so does arriving log data, so it says little about when anything else about the agent changed.
deleted_at date-time or nullWhen the agent was deleted; null while it is live.
organization_deleted_at date-time or nullWhen the agent's organization was deleted; null while the organization is live.
descriptionstring or nullThe agent's description.
collection_detail any or nullThe detail behind collection_status, as SparkLogs worked it out from the agent's last report. Its contents are not part of the API contract and may change.
collection_feeds map of any or nullHow many of the agent's active feeds report each health, from the same report as collection_status. Keys: current, behind, stuck, blocked, onboarding, onboarding_stuck, unknown, and unrecognized for any other value. A health no feed reports is left out. Null when the agent has reported no feeds.
update_status string or nullWhere the agent's automatic update stands: idle, disabled, in_progress, reboot_pending or failure; null for an agent that has not reported.
update_failure_reason string or nullWhy the agent's last update failed, when it did.
install_id string or nullThe id of the machine the agent is installed on, which stays the same when the agent registers again.
synthetic_install_id string or nullThe agent's install_id when SparkLogs assigned it, because too many machines reported the same machine identity; null when the agent uses its machine's own id.
rollout_seed integer or nullThe agent's place, from 0 to 999999, in a staged update rollout.
archstring or nullThe processor architecture the agent reported.
host_roles array of string or nullThe roles the agent reported for its machine; more values may be added.
registration_token_id uuid or nullThe registration token the agent registered with.
cloned_from_agent_id uuid or nullThe agent this one replaced when its machine was found to be a copy of another; null otherwise.
feed_pack_version string or nullThe version of the collection definitions the agent last applied.
last_meta_at date-time or nullWhen SparkLogs last stored the agent's operating system and host details, which it refreshes at most every 15 minutes.
deletionAgentDeletion or nullWhat deleting the agent recorded: whether its machine heard the delete, and when the install comes off. Null while the agent is live.
custom_fields map of any or nullCustom fields recorded on the agent, as an object of string, number and boolean values. Not for secrets: anyone who may read the agent may read them.
host_metadata any or nullThe machine details the agent last reported, as an object. Its contents are not part of the API contract and may change.
agent_data any or nullWhat the agent reported about its collection and updates, as an object. Large: it can hold tens of kilobytes per agent. Its contents are not part of the API contract and may change.
List agents
/workspaces/{workspace_id}/agents Returns the SparkLogs Agents you can see, a page at a time, in id order. Seeing an agent takes organization.read and agent.read at its organization. Filter by organization, with or without the organizations below it, by id, status, inactivity, host, device id or registration token; filters combine, a row passing every one given. agent_status and a moving inactive_before cutoff, such as 14 days before now, are worked out at the walk's as_of, the same instant for every page. host_metadata, agent_data and custom_fields are sent only when fields names them, at most 500 agents a page.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents" ` -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']}"},)response.raise_for_status(){ "agents": [ { "id": "a9e70000-0000-4000-8000-000000000203", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "PD-EXAM-03", "organization_id": "0a9e0000-0000-4000-8000-000000000105", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000105", "a9e70000-0000-4000-8000-000000000203" ], "reported_state": "stopped", "agent_status": "stopped", "reported_state_changed_at": "2026-11-09T18:00:00Z", "collection_status": "unknown", "stuck_reason": null, "last_data_at": "2026-11-09T18:00:00Z", "last_heartbeat_at": "2026-11-09T18:00:00Z", "host_class": "workstation", "reported_hostname": "pd-exam-03", "rmm_device_id": null, "psa_device_id": null, "agent_version": "1.14.3", "os_family": "windows", "os_version": "10.0.22631", "created_at": "2026-11-05T08:00:00Z", "updated_at": "2026-11-09T18:00:00Z", "deleted_at": null, "organization_deleted_at": null }, { "id": "a9e70000-0000-4000-8000-000000000201", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "FIN-LT-04", "organization_id": "0a9e0000-0000-4000-8000-000000000102", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000102", "a9e70000-0000-4000-8000-000000000201" ], "reported_state": "running", "agent_status": "online", "reported_state_changed_at": "2026-11-03T12:00:00Z", "collection_status": "healthy", "stuck_reason": null, "last_data_at": "2026-11-10T15:00:00Z", "last_heartbeat_at": "2026-11-10T15:00:00Z", "host_class": "workstation", "reported_hostname": "fin-lt-04", "rmm_device_id": null, "psa_device_id": null, "agent_version": "1.14.4", "os_family": "windows", "os_version": "10.0.22631", "created_at": "2026-11-03T12:00:00Z", "updated_at": "2026-11-10T15:00:00Z", "deleted_at": null, "organization_deleted_at": null }, { "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}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
agent.read
Needs agent.read. agent.read applies at each organization a grant covers and every organization below it. agent.read also admits reading ingest keys, but never their secrets. A caller who reaches no organization gets an empty list.
Behavior
- Retry
- Safe to send again
- Paging
- Cursor · 1000 a page by default, up to 5000
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
organization_id uuidOnly agents of this organization.
subtreebooleantrue adds the agents of every organization below organization_id. true and false are the only values it takes.
idarray of stringOnly the agents with these ids. A comma-separated list of at most 100 ids matches any of them.
agent_status array of one of the values belowOnly agents reading one of these agent_status values. Deleted agents are listed with deleted, not here. A comma-separated list matches any of its values. Worked out at the walk's as_of.
onlineChecked in or sent data in the last 15 minutes.offlineNothing has arrived for longer than that, and the agent did not say it was stopping.never_seenEnrolled, and nothing has arrived from it yet.stoppedThe agent said its service was stopped.system_shutdownThe agent said its machine was shutting down.uninstalledThe agent said it was being uninstalled.upgrading_overdueThe agent said it was updating itself and has not come back after 30 minutes.
collection_status array of one of the values belowOnly agents reporting one of these collection_status values, the same buckets read-agent-summary counts. A comma-separated list matches any of its values.
healthyThe agent reportshealthy.behindThe agent reportsbehind.onboardingThe agent reportsonboarding.degradedThe agent reportsdegraded.unknownThe agent reportsunknown.noneNo collection status worked out yet:collection_statusis null.
inactive_before date-timeOnly agents that were created, last sent data, last checked in and last changed status before this time: what inactive counts on read-agent-summary, at a cutoff you choose. An RFC 3339 time.
host_class array of stringOnly agents of these host_class values, such as server. A value no agent reports matches nothing. A comma-separated list matches any of its values, each exactly and ignoring case. Spaces around the value are ignored.
install_id stringOnly agents with this install_id: every record of one machine, such as the live one a refused restore or move conflicts with. Spaces around the value are ignored.
reported_hostname stringOnly agents whose reported_hostname is this. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
registration_token_id uuidOnly agents that registered with this registration token.
rmm_device_id stringOnly agents recording this rmm_device_id; every one is returned. Spaces around the value are ignored.
psa_device_id stringOnly agents recording this psa_device_id; every one is returned. Spaces around the value are ignored.
deletedone of the values belowWhich agents to list, by whether they or their organization are deleted.
excludeAgents that are live in a live organization. The default.includeEvery agent, deleted ones and those of deleted organizations included.onlyAgents that are deleted or whose organization is.
limitintegerHow many agents a page holds: 1 to 5000, 1000 by default; at most 500, and 500 by default, with a heavy field.
cursorstringThe next_cursor of the previous page, with the same filters.
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: idworkspace_idnameorganization_idpathreported_stateagent_statusreported_state_changed_atcollection_statusstuck_reasonlast_data_atlast_heartbeat_athost_classreported_hostnamermm_device_idpsa_device_idagent_versionos_familyos_versioncreated_atupdated_atdeleted_atorganization_deleted_at
Sent only when named in fields: descriptioncollection_detailcollection_feedsupdate_statusupdate_failure_reasoninstall_idsynthetic_install_idrollout_seedarchhost_rolesregistration_token_idcloned_from_agent_idfeed_pack_versionlast_meta_atdeletioncustom_fieldshost_metadataagent_data
Response 200
The agents on this page.
next_cursor string or nullrequiredNull on the last page. Otherwise pass it as cursor for the next page.
as_of date-timerequiredThe instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, one given twice, or fields naming a field it does not have.NoAPP_API_ERR_BAD_PARAMETERS A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; parameter names the filter.NoAPP_API_ERR_BAD_PARAMETERS organization_id is not a UUID, subtree is neither true nor false or comes without organization_id, deleted is not a value it takes, or limit is out of range, or cursor cannot be read or was sent with other filters.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold organization.read and agent.read. The same refusal comes when the path names a workspace other than the token's own.NoPlus the errors every call can return.
Related
Read an agent
/workspaces/{workspace_id}/agents/{id} Returns one SparkLogs Agent you can see, deleted or not, with every field but collection_detail, rollout_seed, host_metadata, agent_data and custom_fields unless fields names them. One you cannot see returns 404, as one that does not exist does, and so does the id of an ingest key.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000201" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000201" ` -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/a9e70000-0000-4000-8000-000000000201" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "agent": { "id": "a9e70000-0000-4000-8000-000000000201", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "FIN-LT-04", "organization_id": "0a9e0000-0000-4000-8000-000000000102", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000102", "a9e70000-0000-4000-8000-000000000201" ], "reported_state": "running", "agent_status": "online", "reported_state_changed_at": "2026-11-03T12:00:00Z", "collection_status": "healthy", "stuck_reason": null, "last_data_at": "2026-11-10T15:00:00Z", "last_heartbeat_at": "2026-11-10T15:00:00Z", "host_class": "workstation", "reported_hostname": "fin-lt-04", "rmm_device_id": null, "psa_device_id": null, "agent_version": "1.14.4", "os_family": "windows", "os_version": "10.0.22631", "created_at": "2026-11-03T12:00:00Z", "updated_at": "2026-11-10T15:00:00Z", "deleted_at": null, "organization_deleted_at": null, "description": null, "collection_feeds": null, "update_status": null, "update_failure_reason": null, "install_id": null, "synthetic_install_id": null, "arch": null, "host_roles": null, "registration_token_id": null, "cloned_from_agent_id": null, "feed_pack_version": null, "last_meta_at": null, "deletion": null }, "message": "agent retrieved"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
agent.read
Needs agent.read. agent.read applies at each organization a grant covers and every organization below it. agent.read also admits reading ingest keys, but never their secrets.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe agent's id.
Query parameters
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: idworkspace_idnameorganization_idpathreported_stateagent_statusreported_state_changed_atcollection_statusstuck_reasonlast_data_atlast_heartbeat_athost_classreported_hostnamermm_device_idpsa_device_idagent_versionos_familyos_versioncreated_atupdated_atdeleted_atorganization_deleted_atdescriptioncollection_feedsupdate_statusupdate_failure_reasoninstall_idsynthetic_install_idarchhost_rolesregistration_token_idcloned_from_agent_idfeed_pack_versionlast_meta_atdeletion
Sent only when named in fields: collection_detailrollout_seedcustom_fieldshost_metadataagent_data
Response 200
The agent.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, one given twice, or fields naming a field it does not have.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold organization.read and agent.read. The same refusal comes when the path names a workspace other than the token's own.No404APP_API_ERR_RECORD_NOT_FOUND No such agent, or one you cannot see; an ingest key's id answers this too.NoPlus the errors every call can return.
Related
Count agents
/workspaces/{workspace_id}/agents/summary Returns how many SparkLogs Agents you can see are enrolled, active since active_since and inactive, and how many read each agent_status and report each collection_status, worked out at one moment. It reports on the agents, and says nothing of the devices' own health, such as disk, CPU or patches. To list the agents behind a count, list the agents. Counting an agent takes organization.read and agent.read at its organization; a count never includes an agent you cannot see, and holding both nowhere together returns 403. Narrow it to an organization, with or without the organizations below it; a deleted one returns 400, since only live organizations are counted, and one you cannot see returns 404.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/summary" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/summary" ` -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/summary" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "agent_summary": { "as_of": "2026-11-10T15:00:00Z", "active_since": "2026-10-27T15:00:00Z", "inactive_before": "2026-10-27T15:00:00Z", "enrolled": 3, "active": 3, "inactive": 0, "by_agent_status": { "online": 2, "offline": 0, "never_seen": 0, "stopped": 1, "system_shutdown": 0, "uninstalled": 0, "upgrading_overdue": 0 }, "by_collection_status": { "healthy": 1, "behind": 1, "onboarding": 0, "degraded": 0, "unknown": 1, "none": 0 } }, "message": "summary retrieved"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
agent.read
Needs agent.read. agent.read applies at each organization a grant covers and every organization below it. agent.read also admits reading ingest keys, but never their secrets.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
organization_id uuidOnly the agents of this organization.
subtreebooleantrue adds the agents of every organization below organization_id. true and false are the only values it takes.
active_since date-timeWhere the active count starts (RFC 3339), such as the start of the period a dashboard shows. 14 days before as_of by default.
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: as_ofactive_sinceinactive_beforeenrolledactiveinactiveby_agent_statusby_collection_status
Response 200
agent_summary AgentSummaryrequiredThe agent summary.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, one given twice, or fields naming a field it does not have.NoAPP_API_ERR_BAD_PARAMETERS organization_id is not a UUID or names a deleted organization, subtree is neither true nor false or comes without it, or active_since is not a valid time.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold organization.read and agent.read together at any organization. The same refusal comes when the path names a workspace other than the token's own.No404APP_API_ERR_RECORD_NOT_FOUND organization_id names an organization you cannot see.NoPlus the errors every call can return.
Related
Update an agent
/workspaces/{workspace_id}/agents/{id} Changes a SparkLogs Agent's name, description, device ids or custom fields; a field left out keeps its value. The name follows the machine's host name until someone sets a different name; to make it follow again, set it to the current reported_hostname, in any case. To label an agent and keep its name following, set description. Needs agent.write at its organization.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PATCH \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "WB-PC-04 front desk" }'$body = @{ name = "WB-PC-04 front desk"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.patch( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "WB-PC-04 front desk", },)response.raise_for_status(){ "message": "agent updated", "id": "a9e70000-0000-4000-8000-000000000202"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
agent.write
Needs agent.write. agent.write applies at each organization a grant covers and every organization below it. agent.write also admits changing and moving ingest keys.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe agent's id.
Request body
No field is required. Send no body to accept the defaults.
namestringThe new name, cleaned as every name is. The name follows the machine's host name until a different name is set here; setting it to the current reported_hostname, in any case, makes it follow again. To label the agent and keep its name following, set description instead. null or an empty string returns 400.
left out keeps · null is refused · empty string is refused
descriptionstring or nullThe new description. null or an empty string clears it.
left out keeps · null clears · empty string clears
rmm_device_id string or nullThe id your RMM uses for the agent's machine, cleaned as every name is. A later registration of the machine that names no id keeps it. null or an empty string clears it.
left out keeps · null clears · empty string clears
psa_device_id string or nullThe id your PSA uses for the agent's machine, cleaned as every name is. A later registration of the machine that names no id keeps it. null or an empty string clears it.
left out keeps · null clears · empty string clears
custom_fields map of any or nullChanges to the custom fields, merged into the stored ones: a key left out keeps its value, null removes it, and a string, a boolean, or a number of at most 32 characters in plain decimal digits with no exponent sets it. A number is kept by its value, so 1.50 reads back as 1.5. At most 50 keys, each 1 to 64 letters, digits, _, - and ., and 8 KiB as JSON. Write a time as RFC 3339 in UTC. Not for secrets.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.NoAPP_API_ERR_BAD_PARAMETERS name is empty.NoAPP_API_ERR_PARAMETER_TOO_LONG name is longer than 128 characters, or description longer than 2048.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe agent does not exist, is in another workspace or is outside your reach, id names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Delete an agent
/workspaces/{workspace_id}/agents/{id} Marks a SparkLogs Agent deleted; its machine is refused from then on, and cache_clear_status says whether every region refuses it. The query parameter uninstall says when the machine removes the install: on that date the agent removes itself, with its local state when uninstall_purge is true, and left out the date is 60 days after the first delete. The options are query parameters because some HTTP clients and proxies drop or refuse a body on DELETE, which would delete the agent without scheduling its removal; a body is refused. Needs agent.delete at its organization. Deleting a deleted agent changes nothing, except that a named uninstall replaces the stored schedule. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 2 hours.
- Request
- Response
- curl
- PowerShell
- Python
curl -X DELETE \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203?uninstall=after_days&uninstall_days=7" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203?uninstall=after_days&uninstall_days=7" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "uninstall": "after_days", "uninstall_days": "7", },)response.raise_for_status(){ "message": "agent deleted", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
agent.delete
Needs agent.delete. agent.delete applies at each organization a grant covers and every organization below it. agent.delete also admits deleting and restoring ingest keys.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe agent's id.
Query parameters
uninstallone of the values belowWhen the agent's machine removes the install. Left out, a first delete records the default of 60 days and a repeated one keeps what is stored; given on a repeated delete, it replaces the stored schedule.
after_daysAfter the number of days inuninstall_days.immediatelyAs soon as the agent learns of the delete.neverThe install stays on the machine.
uninstall_days integerWith after_days, how many days after the delete: 1 to 365, 60 by default.
uninstall_purge booleantrue also deletes what the agent keeps on the machine: its settings, its identity, the events it buffered and not yet sent, and its logs. Left out, they stay, and installing the agent there again later carries on from them. true and false are the only values it takes.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS uninstall is not one of the values it takes, uninstall_days is not a whole number from 1 to 365 or comes with uninstall other than after_days, uninstall_purge is not true or false or comes with uninstall never, or uninstall_days or uninstall_purge comes without uninstall; parameter names the parameter.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The request carries a body other than nothing, null or {}: a delete takes none, and its options are query parameters; parameter names the body's first field, or body.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe agent does not exist, is in another workspace or is outside your reach, id names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Restore a deleted agent
/workspaces/{workspace_id}/agents/{id}/restore Restores a deleted SparkLogs Agent. It cancels a pending uninstall; an agent already removed from its machine is not reinstalled. Another live agent in its organization with the same install id returns 409. Needs agent.delete at its organization. Restoring a live agent changes nothing. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 2 hours.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203/restore" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203/restore" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203/restore" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "agent restored", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
agent.delete
Needs agent.delete. agent.delete applies at each organization a grant covers and every organization below it. agent.delete also admits deleting and restoring ingest keys.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe agent's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe agent does not exist, is in another workspace or is outside your reach, id names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No409APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED Its organization is deleted.NoAPP_API_ERR_ALREADY_TAKEN Another live agent in its organization carries its machine's install id; parameter is install_id.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Move an agent
/workspaces/{workspace_id}/agents/{id}/move Moves a SparkLogs Agent to another organization. Needs agent.write at its organization and ingest_key.create at the new one. Another live agent there with the same install id returns 409. Moving it where it already is changes nothing. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 2 hours.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202/move" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "organization_id": "0a9e0000-0000-4000-8000-000000000101" }'$body = @{ organization_id = "0a9e0000-0000-4000-8000-000000000101"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202/move" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202/move" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "organization_id": "0a9e0000-0000-4000-8000-000000000101", },)response.raise_for_status(){ "message": "agent moved", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
agent.writeingest_key.create
Needs agent.write at the organization it is in now and ingest_key.create at the organization it moves to. agent.write applies at each organization a grant covers and every organization below it. agent.write also admits changing and moving ingest keys. ingest_key.create applies at each organization a grant covers and every organization below it. ingest_key.create also admits moving a SparkLogs Agent or an ingest key into an organization, with agent.write at the one it leaves.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe agent's id.
Request body
organization_id uuidrequiredThe organization to move it to. Moving needs agent.write at the agent's organization and ingest_key.create at this one. Required.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.NoAPP_API_ERR_MISSING_PARAMETER organization_id is left out.NoAPP_API_ERR_BAD_PARAMETERS organization_id is not a UUID, or names a deleted organization for a live agent.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe agent or the new organization does not exist or is outside your reach, id names an ingest key, or you do not hold agent.write at the agent's organization and ingest_key.create at the new one. The same refusal comes when the path names a workspace other than the token's own.No409APP_API_ERR_ALREADY_TAKEN Another live agent in the new organization carries the agent's machine install id; parameter is install_id.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.