Skip to main content

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.

Agent object​

An agent is a SparkLogs Agent installed on a machine: it reports whether it is in contact and how its collection stands.

iduuid

The agent's id.

workspace_iduuid

The workspace the agent belongs to.

namestring or null

The 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_iduuid

The organization the agent belongs to.

patharray of uuid or null

The organization ids from the top-level organization down to the agent's own, then the agent's id.

reported_statestring or null

The 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_statusone of the values below

Whether 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.

  • online The agent checked in or sent data in the last 15 minutes.
  • offline Nothing has arrived for longer than that, and the agent did not say it was stopping; the cause is unknown.
  • never_seen Enrolled, and nothing has arrived from it yet.
  • stopped The agent said its service was stopped.
  • system_shutdown The agent said its machine was shutting down.
  • uninstalled The agent said it was being uninstalled.
  • upgrading_overdue The agent said it was updating itself and has not come back after 30 minutes.
  • deleted The agent is deleted.
reported_state_changed_atdate-time or null

When reported_state last changed.

collection_statusstring or null

SparkLogs' 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_reasonstring or null

Why the agent is checking in but not collecting; null while it collects.

last_data_atdate-time or null

When 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_atdate-time or null

When the agent last checked in, about every five minutes while it runs. Null until it first checks in.

host_classstring or null

The kind of machine the agent runs on: workstation or server today, and more values may be added.

reported_hostnamestring or null

The host name the agent reported, in lower case.

rmm_device_idstring or null

The 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_idstring or null

The 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_versionstring or null

The agent's version.

os_familystring or null

The operating system family the agent reported.

os_versionstring or null

The operating system version the agent reported.

created_atdate-time

When the agent was created.

updated_atdate-time

When 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_atdate-time or null

When the agent was deleted; null while it is live.

organization_deleted_atdate-time or null

When the agent's organization was deleted; null while the organization is live.

descriptionstring or null

The agent's description.

collection_detailany or null

The 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_feedsmap of any or null

How 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_statusstring or null

Where the agent's automatic update stands: idle, disabled, in_progress, reboot_pending or failure; null for an agent that has not reported.

update_failure_reasonstring or null

Why the agent's last update failed, when it did.

install_idstring or null

The id of the machine the agent is installed on, which stays the same when the agent registers again.

synthetic_install_idstring or null

The 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_seedinteger or null

The agent's place, from 0 to 999999, in a staged update rollout.

archstring or null

The processor architecture the agent reported.

host_rolesarray of string or null

The roles the agent reported for its machine; more values may be added.

registration_token_iduuid or null

The registration token the agent registered with.

cloned_from_agent_iduuid or null

The agent this one replaced when its machine was found to be a copy of another; null otherwise.

feed_pack_versionstring or null

The version of the collection definitions the agent last applied.

last_meta_atdate-time or null

When SparkLogs last stored the agent's operating system and host details, which it refreshes at most every 15 minutes.

deletionAgentDeletion or null

What deleting the agent recorded: whether its machine heard the delete, and when the install comes off. Null while the agent is live.

custom_fieldsmap of any or null

Custom 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_metadataany or null

The machine details the agent last reported, as an object. Its contents are not part of the API contract and may change.

agent_dataany or null

What 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​

GET/workspaces/{workspace_id}/agents
Preview

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.

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

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_iduuidrequired

The workspace's id.

Query parameters

organization_iduuid

Only agents of this organization.

subtreeboolean

true adds the agents of every organization below organization_id. true and false are the only values it takes.

Default: false

idarray of string

Only the agents with these ids. A comma-separated list of at most 100 ids matches any of them.

agent_statusarray of one of the values below

Only 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.

  • online Checked in or sent data in the last 15 minutes.
  • offline Nothing has arrived for longer than that, and the agent did not say it was stopping.
  • never_seen Enrolled, and nothing has arrived from it yet.
  • stopped The agent said its service was stopped.
  • system_shutdown The agent said its machine was shutting down.
  • uninstalled The agent said it was being uninstalled.
  • upgrading_overdue The agent said it was updating itself and has not come back after 30 minutes.
collection_statusarray of one of the values below

Only agents reporting one of these collection_status values, the same buckets read-agent-summary counts. A comma-separated list matches any of its values.

  • healthy The agent reports healthy.
  • behind The agent reports behind.
  • onboarding The agent reports onboarding.
  • degraded The agent reports degraded.
  • unknown The agent reports unknown.
  • none No collection status worked out yet: collection_status is null.
inactive_beforedate-time

Only 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_classarray of string

Only 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_idstring

Only 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_hostnamestring

Only 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_iduuid

Only agents that registered with this registration token.

rmm_device_idstring

Only agents recording this rmm_device_id; every one is returned. Spaces around the value are ignored.

psa_device_idstring

Only agents recording this psa_device_id; every one is returned. Spaces around the value are ignored.

deletedone of the values below

Which agents to list, by whether they or their organization are deleted.

  • exclude Agents that are live in a live organization. The default.
  • include Every agent, deleted ones and those of deleted organizations included.
  • only Agents that are deleted or whose organization is.

Default: exclude

limitinteger

How many agents a page holds: 1 to 5000, 1000 by default; at most 500, and 500 by default, with a heavy field.

Default: 10001 to 5000

cursorstring

The next_cursor of the previous page, with the same filters.

fieldsarray of string

Comma-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

agentsarray of Agentrequired

The agents on this page.

next_cursorstring or nullrequired

Null on the last page. Otherwise pass it as cursor for the next page.

as_ofdate-timerequired

The 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.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, one given twice, or fields naming a field it does not have.No
400APP_API_ERR_BAD_PARAMETERSA 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.No
400APP_API_ERR_BAD_PARAMETERSorganization_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.No
403APP_API_ERR_NO_PRIVILEGEtoken_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.No

Plus the errors every call can return.

Related

Read an agent​

GET/workspaces/{workspace_id}/agents/{id}
Preview

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.

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"

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_iduuidrequired

The workspace's id.

iduuidrequired

The agent's id.

Query parameters

fieldsarray of string

Comma-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

agentAgentrequired

The agent.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, one given twice, or fields naming a field it does not have.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
403APP_API_ERR_NO_PRIVILEGEtoken_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.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such agent, or one you cannot see; an ingest key's id answers this too.No

Plus the errors every call can return.

Related

Count agents​

GET/workspaces/{workspace_id}/agents/summary
Preview

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.

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

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_iduuidrequired

The workspace's id.

Query parameters

organization_iduuid

Only the agents of this organization.

subtreeboolean

true adds the agents of every organization below organization_id. true and false are the only values it takes.

Default: false

active_sincedate-time

Where 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 string

Comma-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_summaryAgentSummaryrequired

The agent summary.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, one given twice, or fields naming a field it does not have.No
400APP_API_ERR_BAD_PARAMETERSorganization_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.No
403APP_API_ERR_NO_PRIVILEGEtoken_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.No
404APP_API_ERR_RECORD_NOT_FOUNDorganization_id names an organization you cannot see.No

Plus the errors every call can return.

Related

Update an agent​

PATCH/workspaces/{workspace_id}/agents/{id}
Preview

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.

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

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_iduuidrequired

The workspace's id.

iduuidrequired

The agent's id.

Request body

No field is required. Send no body to accept the defaults.

namestring

The 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

at most 128 characters

descriptionstring or null

The new description. null or an empty string clears it.

left out keeps · null clears · empty string clears

at most 2048 characters

rmm_device_idstring or null

The 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

at most 256 characters

psa_device_idstring or null

The 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

at most 256 characters

custom_fieldsmap of any or null

Changes 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

iduuidrequired

The id of the row the call created or changed.

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This 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_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe 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.No
400APP_API_ERR_BAD_PARAMETERSname is empty.No
400APP_API_ERR_PARAMETER_TOO_LONGname is longer than 128 characters, or description longer than 2048.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_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.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Delete an agent​

DELETE/workspaces/{workspace_id}/agents/{id}
PreviewDestructive

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.

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"

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_iduuidrequired

The workspace's id.

iduuidrequired

The agent's id.

Query parameters

uninstallone of the values below

When 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_days After the number of days in uninstall_days.
  • immediately As soon as the agent learns of the delete.
  • never The install stays on the machine.
uninstall_daysinteger

With after_days, how many days after the delete: 1 to 365, 60 by default.

Default: 601 to 365

uninstall_purgeboolean

true 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.

Default: false

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This 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_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSuninstall 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.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe 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.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_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.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Restore a deleted agent​

POST/workspaces/{workspace_id}/agents/{id}/restore
Preview

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.

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"

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_iduuidrequired

The workspace's id.

iduuidrequired

The agent's id.

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This 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_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_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.No
409APP_API_ERR_CANNOT_RESTORE_PARENT_DELETEDIts organization is deleted.No
409APP_API_ERR_ALREADY_TAKENAnother live agent in its organization carries its machine's install id; parameter is install_id.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Move an agent​

POST/workspaces/{workspace_id}/agents/{id}/move
Preview

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.

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

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_iduuidrequired

The workspace's id.

iduuidrequired

The agent's id.

Request body

organization_iduuidrequired

The 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_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This 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_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe 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.No
400APP_API_ERR_MISSING_PARAMETERorganization_id is left out.No
400APP_API_ERR_BAD_PARAMETERSorganization_id is not a UUID, or names a deleted organization for a live agent.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_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.No
409APP_API_ERR_ALREADY_TAKENAnother live agent in the new organization carries the agent's machine install id; parameter is install_id.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related