Ingest keys
An ingest key lets a sender other than a SparkLogs Agent send log data for an organization; list and read them, create one, read or replace its secret, and rename, move, delete or restore one.
A SparkLogs Agent's id names no ingest key here, and returns 404 to a read and 403 to a change, as an id that does not exist does.
Belongs to: Workspaces, Organizations
- GET
List ingest keys/workspaces /{workspace_id} /ingest-keys - GET
Read an ingest key/workspaces /{workspace_id} /ingest-keys /{id} - POST
Create an ingest key/workspaces /{workspace_id} /ingest-keys - PATCH
Update an ingest key/workspaces /{workspace_id} /ingest-keys /{id} - DELETE
Delete an ingest key/workspaces /{workspace_id} /ingest-keys /{id} - POST
Restore a deleted ingest key/workspaces /{workspace_id} /ingest-keys /{id} /restore - POST
Move an ingest key/workspaces /{workspace_id} /ingest-keys /{id} /move - GET
Read an ingest key's secret/workspaces /{workspace_id} /ingest-keys /{id} /secret - POST
Replace an ingest key's secret/workspaces /{workspace_id} /ingest-keys /{id} /rotate
IngestKey object
An ingest key is a secret a sender other than a SparkLogs Agent presents to send log data for one organization.
iduuidThe ingest key's id.
workspace_id uuidThe workspace the ingest key belongs to.
namestring or nullThe ingest key's name, a label that changes only when you change it.
descriptionstring or nullThe ingest key's description.
organization_id uuidThe organization the ingest key sends data for.
patharray of uuid or nullThe organization ids from the top-level organization down to the key's own, then the key's id.
data_status one of the values belowWhether data is arriving with the key, worked out from when its data last arrived: on a list at the page's as_of, the same instant for every page of one walk, and on a read of one key when the response is written. A key has no heartbeat, so a sender that sends nothing for hours reads offline. The SparkLogs MCP server shows the same value as agent_status on an ingest key's row.
onlineData arrived with the key in the last 3 hours.offlineNo data has arrived with it for longer than that.never_seenNo data has arrived with it yet.deletedThe ingest key is deleted.
last_data_at date-time or nullWhen log data sent with the key last arrived, recorded at most once every five minutes. Null until data first arrives.
created_at date-timeWhen the ingest key was created.
updated_at date-timeWhen the ingest key's record last changed. Arriving data changes it, so it says little about when anything else about the key changed.
deleted_at date-time or nullWhen the ingest key was deleted; null while it is live.
organization_deleted_at date-time or nullWhen the key's organization was deleted; null while the organization is live.
custom_fields map of any or nullCustom fields recorded on the ingest key, as an object of string, number and boolean values. Not for secrets: anyone who may read the ingest key may read them.
List ingest keys
/workspaces/{workspace_id}/ingest-keys Returns the ingest keys you can see, a page at a time, in id order, never with their secrets. Seeing a key takes organization.read and agent.read at its organization. Filter by organization, with or without the organizations below it, by name, or by inactivity; filters combine, a row passing every one given. A moving inactive_before cutoff, such as 14 days before now, and data_status are worked out at the walk's as_of, the same instant for every page.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" ` -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/ingest-keys" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "as_of": "2026-11-10T15:05:00Z", "ingest_keys": [ { "id": "a9e70000-0000-4000-8000-000000000204", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "Harbor Dental servers", "description": null, "organization_id": "0a9e0000-0000-4000-8000-000000000105", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000105", "a9e70000-0000-4000-8000-000000000204" ], "data_status": "online", "last_data_at": "2026-11-10T14:00:00Z", "created_at": "2026-11-05T08:00:00Z", "updated_at": "2026-11-10T14:00:00Z", "deleted_at": null, "organization_deleted_at": null }, { "id": "a9e70000-0000-4000-8000-000000000205", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "Lakeside Clinic firewall", "description": "Syslog from the front office firewall", "organization_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "a9e70000-0000-4000-8000-000000000205" ], "data_status": "online", "last_data_at": "2026-11-10T15:00:00Z", "created_at": "2026-11-03T14:00:00Z", "updated_at": "2026-11-10T15:00:00Z", "deleted_at": null, "organization_deleted_at": null } ], "message": "ingest keys 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 ingest keys of this organization.
subtreebooleantrue adds the ingest keys of every organization below organization_id. true and false are the only values it takes.
idarray of stringOnly the ingest keys with these ids. A comma-separated list of at most 100 ids matches any of them.
namestringOnly ingest keys of this name: the way to find a key created by a call whose answer was lost. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
inactive_before date-timeOnly ingest keys created, and last sending data, before this time: keys gone quiet, at a cutoff you choose. An RFC 3339 time.
deletedone of the values belowWhich ingest keys to list, by whether they or their organization are deleted.
excludeIngest keys that are live in a live organization. The default.includeEvery ingest key, deleted ones and those of deleted organizations included.onlyIngest keys that are deleted or whose organization is.
limitintegerHow many ingest keys a page holds: 1 to 5000, 1000 by default.
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_idnamedescriptionorganization_idpathdata_statuslast_data_atcreated_atupdated_atdeleted_atorganization_deleted_at
Sent only when named in fields: custom_fields
Response 200
The ingest keys 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 ingest key
/workspaces/{workspace_id}/ingest-keys/{id} Returns one ingest key you can see, deleted or not, without its secret. One you cannot see returns 404, as one that does not exist does, and so does the id of a SparkLogs Agent.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204" ` -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/ingest-keys/a9e70000-0000-4000-8000-000000000204" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "ingest_key": { "id": "a9e70000-0000-4000-8000-000000000204", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "Harbor Dental servers", "description": null, "organization_id": "0a9e0000-0000-4000-8000-000000000105", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000105", "a9e70000-0000-4000-8000-000000000204" ], "data_status": "online", "last_data_at": "2026-11-10T14:00:00Z", "created_at": "2026-11-05T08:00:00Z", "updated_at": "2026-11-10T14:00:00Z", "deleted_at": null, "organization_deleted_at": null }, "message": "ingest key 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 ingest key'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_idnamedescriptionorganization_idpathdata_statuslast_data_atcreated_atupdated_atdeleted_atorganization_deleted_at
Sent only when named in fields: custom_fields
Response 200
The ingest key.
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 ingest key, or one you cannot see; a SparkLogs Agent's id answers this too.NoPlus the errors every call can return.
Related
Create an ingest key
/workspaces/{workspace_id}/ingest-keys Creates an ingest key for organization_id and returns the key senders present. Needs ingest_key.create at that organization.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Harbor Dental servers", "organization_id": "0a9e0000-0000-4000-8000-000000000105" }'$body = @{ name = "Harbor Dental servers" organization_id = "0a9e0000-0000-4000-8000-000000000105"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" ` -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/ingest-keys" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Harbor Dental servers", "organization_id": "0a9e0000-0000-4000-8000-000000000105", },)response.raise_for_status(){ "message": "ingest key created", "id": "a9e70000-0000-4000-8000-000000000204", "key": "EXAMPLE-INGEST-KEY-NOT-A-REAL-SECRET"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
- any of
fleet:deployfleet:write - Privilege
ingest_key.create
Needs ingest_key.create. 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
- Read before sending again
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
Request body
organization_id uuidrequiredThe organization the ingest key sends data for. Required.
namestringrequiredThe ingest key's name. Cleaned, as every name is. Required.
descriptionstring or nullThe ingest key's description.
Response 200
iduuidrequiredThe new ingest key's id.
keystringrequiredThe key a sender presents to send log data. Keep it secret; it can be read again later by anyone holding ingest_key.reveal.
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 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 or name is left out or empty.NoAPP_API_ERR_BAD_PARAMETERS organization_id is not a UUID or names a deleted organization.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_privilegeYou do not hold ingest_key.create at organization_id, or it names no organization you can see. 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
Update an ingest key
/workspaces/{workspace_id}/ingest-keys/{id} Changes an ingest key's name, description or custom fields; a field left out keeps its value. 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/ingest-keys/a9e70000-0000-4000-8000-000000000204" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Harbor Dental server room" }'$body = @{ name = "Harbor Dental server room"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204" ` -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/ingest-keys/a9e70000-0000-4000-8000-000000000204" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Harbor Dental server room", },)response.raise_for_status(){ "message": "ingest key updated", "id": "a9e70000-0000-4000-8000-000000000204"}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 ingest key's id.
Request body
No field is required. Send no body to accept the defaults.
namestringThe new name, a label only. Cleaned, as every name is. 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
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 ingest key does not exist, is in another workspace or is outside your reach, id names a SparkLogs Agent, 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 ingest key
/workspaces/{workspace_id}/ingest-keys/{id} Marks an ingest key deleted; senders using it are refused from then on, and cache_clear_status says whether every region refuses it. Needs agent.delete at its organization. Deleting a deleted key 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 DELETE \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000205" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000205" ` -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/ingest-keys/a9e70000-0000-4000-8000-000000000205" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "ingest key 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 ingest key'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 A query parameter it does not take, or one given twice.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 ingest key does not exist, is in another workspace or is outside your reach, id names a SparkLogs Agent, 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 ingest key
/workspaces/{workspace_id}/ingest-keys/{id}/restore Restores a deleted ingest key, so senders using it are accepted again. Needs agent.delete at its organization. Restoring a live key 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/ingest-keys/a9e70000-0000-4000-8000-000000000205/restore" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000205/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/ingest-keys/a9e70000-0000-4000-8000-000000000205/restore" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "ingest key 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 ingest key'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 ingest key does not exist, is in another workspace or is outside your reach, id names a SparkLogs Agent, 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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Move an ingest key
/workspaces/{workspace_id}/ingest-keys/{id}/move Moves an ingest key to another organization; data sent with it from then on belongs to the new one. Needs agent.write at its organization and ingest_key.create at the new one. 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/ingest-keys/a9e70000-0000-4000-8000-000000000204/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/ingest-keys/a9e70000-0000-4000-8000-000000000204/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/ingest-keys/a9e70000-0000-4000-8000-000000000204/move" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "organization_id": "0a9e0000-0000-4000-8000-000000000101", },)response.raise_for_status(){ "message": "ingest key 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 ingest key's id.
Request body
organization_id uuidrequiredThe organization to move it to. Moving needs agent.write at the key'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 key.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe ingest key or the new organization does not exist or is outside your reach, id names a SparkLogs Agent, or you do not hold agent.write at the key'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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Read an ingest key's secret
/workspaces/{workspace_id}/ingest-keys/{id}/secret Returns the key senders present. It changes nothing. Needs ingest_key.reveal at the ingest key's organization. Every call is recorded in the audit log.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/secret" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/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/ingest-keys/a9e70000-0000-4000-8000-000000000204/secret" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "key retrieved", "key": "EXAMPLE-INGEST-KEY-NOT-A-REAL-SECRET"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
- any of
fleet:deployfleet:write - Privilege
ingest_key.reveal
Needs ingest_key.reveal. ingest_key.reveal applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to send again
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe ingest key's id.
Response 200
keystringrequiredThe key a sender presents to send log data.
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 id is not a UUID.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeYou do not hold ingest_key.reveal at its organization, or it is missing, outside your reach or a SparkLogs Agent. The same refusal comes when the path names a workspace other than the token's own.No409APP_API_ERR_CONFLICT The ingest key is deleted: restore it first.Read firstPlus the errors every call can return.
Related
Replace an ingest key's secret
/workspaces/{workspace_id}/ingest-keys/{id}/rotate Replaces the key senders present with a new one and returns it; senders still using the old key are refused from then on, and cache_clear_status says whether every region refuses it. Needs ingest_key.rotate at the ingest key's organization. Every call is recorded in the audit log. 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/ingest-keys/a9e70000-0000-4000-8000-000000000204/rotate" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/rotate" ` -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/ingest-keys/a9e70000-0000-4000-8000-000000000204/rotate" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "key replaced", "key": "EXAMPLE-NEW-INGEST-KEY-NOT-A-REAL-SECRET", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
- any of
fleet:deployfleet:write - Privilege
ingest_key.rotate
Needs ingest_key.rotate. ingest_key.rotate applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Read before sending again
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe ingest key's id.
Response 200
keystringrequiredThe new key a sender presents to send log data.
cache_clear_status one of the values belowrequiredWhether every region refuses the old key.
okEvery region refuses the old key.failedA region could not be reached. The old key can keep working there until its cache expires.disabledThis environment does not clear regional caches. The old key can keep working until each region's 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_privilegeYou do not hold ingest_key.rotate at its organization, or it is missing, outside your reach or a SparkLogs Agent. The same refusal comes when the path names a workspace other than the token's own.No409APP_API_ERR_CONFLICT The ingest key is deleted: restore it first.Read first413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.