Organizations
Organizations are the tree your clients and sites live in; list, create, change, move, delete and restore them.
Each organization has at most one parent, and every agent, ingest key and registration token belongs to one organization.
Contains: Agents, Ingest keys, Registration tokens
Forms a tree
- GET
List organizations/workspaces /{workspace_id} /organizations - GET
Read an organization/workspaces /{workspace_id} /organizations /{id} - POST
Create an organization/workspaces /{workspace_id} /organizations - PATCH
Update an organization/workspaces /{workspace_id} /organizations /{id} - DELETE
Delete an organization/workspaces /{workspace_id} /organizations /{id} - POST
Restore a deleted organization/workspaces /{workspace_id} /organizations /{id} /restore - POST
Check a client id/workspaces /{workspace_id} /organizations /client-id-check - POST
Move an organization/workspaces /{workspace_id} /organizations /{id} /move
Organization object
An organization is a client, site or department in the workspace's tree. Each has at most one parent and holds agents, ingest keys and registration tokens.
iduuidThe organization's id.
parent_id uuid or nullThe parent organization's id; null for a top-level organization.
patharray of uuid or nullThe ids from the top-level organization down to this one, ending with its own id.
namestringThe organization's name.
descriptionstring or nullThe organization's description.
rmm_client_id string or nullThe id your RMM uses for this client. Not unique: several organizations may record the same id.
psa_client_id string or nullThe id your PSA uses for this client. Not unique: several organizations may record the same id.
created_at date-timeWhen the organization was created.
updated_at date-timeWhen the organization last changed. A change above it in the tree, such as a parent's move, does not change it.
deleted_at date-time or nullWhen the organization was deleted; null while it is live.
custom_fields map of any or nullCustom fields recorded on the organization, as an object of string, number and boolean values. Not for secrets: anyone who may read the organization may read them.
List organizations
/workspaces/{workspace_id}/organizations Returns the organizations you can see, a page at a time, in id order, or least recently changed first with updated_since. Filters combine: a row must pass every one given. parent_id lists direct children, root_id the organization and everything below it, and name or a client id every organization you can see that records it; passing both client ids returns only organizations recording both. To sync, pass updated_since and keep the watermark of the last page: the next sync starts from it. deleted=include or deleted=only returns deleted organizations too.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" ` -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/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "organizations retrieved", "next_cursor": null, "organizations": [ { "id": "0a9e0000-0000-4000-8000-000000000100", "parent_id": null, "path": [ "0a9e0000-0000-4000-8000-000000000100" ], "name": "Northwind clients", "description": "Every client of Northwind IT Services", "rmm_client_id": null, "psa_client_id": null, "created_at": "2026-11-01T09:00:00Z", "updated_at": "2026-11-01T09:00:00Z", "deleted_at": null }, { "id": "0a9e0000-0000-4000-8000-000000000101", "parent_id": "0a9e0000-0000-4000-8000-000000000100", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101" ], "name": "Lakeside Clinic", "description": "Family practice, two sites", "rmm_client_id": "LAKESIDE-01", "psa_client_id": "10042", "created_at": "2026-11-02T09:00:00Z", "updated_at": "2026-11-02T09:00:00Z", "deleted_at": null }, { "id": "0a9e0000-0000-4000-8000-000000000102", "parent_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000102" ], "name": "Finance", "description": null, "rmm_client_id": null, "psa_client_id": null, "created_at": "2026-11-03T10:00:00Z", "updated_at": "2026-11-03T10:00:00Z", "deleted_at": null }, { "id": "0a9e0000-0000-4000-8000-000000000103", "parent_id": "0a9e0000-0000-4000-8000-000000000100", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000103" ], "name": "Oakridge Medical", "description": null, "rmm_client_id": "OAKRIDGE-01", "psa_client_id": null, "created_at": "2026-11-02T09:00:00Z", "updated_at": "2026-11-04T11:00:00Z", "deleted_at": null }, { "id": "0a9e0000-0000-4000-8000-000000000105", "parent_id": "0a9e0000-0000-4000-8000-000000000100", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000105" ], "name": "Harbor Dental", "description": null, "rmm_client_id": null, "psa_client_id": "10057", "created_at": "2026-11-02T09:00:00Z", "updated_at": "2026-11-09T16:00:00Z", "deleted_at": null } ], "watermark": "2026-11-10T09:00:00Z"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
organization.read
Needs organization.read. organization.read applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.
Behavior
- Retry
- Safe to send again
- Paging
- Cursor, with sync · 1000 a page by default, up to 5000
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
idarray of stringOnly the organizations with these ids. A comma-separated list of at most 100 ids matches any of them.
parent_id uuidOnly the direct children of this organization.
root_id uuidOnly this organization and every organization below it.
namestringOnly organizations of this name: the way to find a site 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.
rmm_client_id stringOnly organizations recording this RMM client id. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
psa_client_id stringOnly organizations recording this PSA client id. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
deletedone of the values belowWhich organizations to list, by whether they are deleted.
excludeLive organizations only. The default.includeLive and deleted organizations.onlyDeleted organizations only.
updated_since date-timeOnly organizations changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.
limitintegerHow many organizations 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: idparent_idpathnamedescriptionrmm_client_idpsa_client_idcreated_atupdated_atdeleted_at
Sent only when named in fields: custom_fields
Response 200
The organizations on this page.
next_cursor string or nullrequiredNull on the last page. Otherwise pass it as cursor for the next page.
watermarkdate-timerequiredPass it as updated_since on your next sync.
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 deleted is not a value it takes, or limit is out of range, cursor cannot be read or was sent with other filters, or updated_since is not a valid time.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold organization.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 organization
/workspaces/{workspace_id}/organizations/{id} Returns one organization you can see, deleted or not. One you cannot see returns 404, as one that does not exist does.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102" ` -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/organizations/0a9e0000-0000-4000-8000-000000000102" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "organization retrieved", "organization": { "id": "0a9e0000-0000-4000-8000-000000000102", "parent_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000102" ], "name": "Finance", "description": null, "rmm_client_id": null, "psa_client_id": null, "created_at": "2026-11-03T10:00:00Z", "updated_at": "2026-11-03T10:00:00Z", "deleted_at": null }}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
organization.read
Needs organization.read. organization.read applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe organization's id.
Query parameters
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: idparent_idpathnamedescriptionrmm_client_idpsa_client_idcreated_atupdated_atdeleted_at
Sent only when named in fields: custom_fields
Response 200
The organization.
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. The same refusal comes when the path names a workspace other than the token's own.No404APP_API_ERR_RECORD_NOT_FOUND No such organization, or one you cannot see.NoPlus the errors every call can return.
Related
Create an organization
/workspaces/{workspace_id}/organizations Creates an organization under parent_id, or at the top level when parent_id is left out. Needs organization.create at the parent, or over every organization for a top-level one. Names are not unique, even among siblings. RMM and PSA client ids need not be unique either; the client id check says which organizations already record one. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 15 minutes.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Finance", "parent_id": "0a9e0000-0000-4000-8000-000000000101" }'$body = @{ name = "Finance" parent_id = "0a9e0000-0000-4000-8000-000000000101"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" ` -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/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Finance", "parent_id": "0a9e0000-0000-4000-8000-000000000101", },)response.raise_for_status(){ "message": "organization created", "id": "0a9e0000-0000-4000-8000-000000000102", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
organization.create
Needs organization.create. organization.create 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.
Request body
parent_id uuid or nullThe organization to create it under; leave it out to create a top-level organization.
namestringrequiredThe organization's name. Cleaned, as every name is. Required.
descriptionstring or nullThe organization's description.
rmm_client_id string or nullThe id your RMM uses for this client, cleaned as every name is. Not unique: other organizations may record the same id. Agent installs that pass this id land here.
psa_client_id string or nullThe id your PSA uses for this client, cleaned as every name is. Not unique: other organizations may record the same id.
Response 200
iduuidrequiredThe new organization's id.
cache_clear_status one of the values belowrequiredHow far the new organization got into every region's cache.
okEvery region's cache has the organization.failedA region could not be reached. The organization exists, and registration tokens and agent installs can use it at once; until that region's cache expires, log searches and the SparkLogs MCP server there can leave it out.disabledThis environment does not clear regional caches. The organization exists, and registration tokens and agent installs can use it at once; until each region's cache expires, log searches and the SparkLogs MCP server can leave it out.
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 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 name is left out or empty.NoAPP_API_ERR_PARAMETER_TOO_LONG name is longer than 128 characters, description longer than 2048, or a client id longer than 256 characters once cleaned.NoAPP_API_ERR_BAD_PARAMETERS parent_id is not a UUID, names a deleted organization, or would make the tree deeper than 25 levels.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeYou do not hold organization.create at parent_id, or parent_id names no organization you can see. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS token_scopeno_privilegeThere is no parent_id and you do not hold organization.create over every organization.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Update an organization
/workspaces/{workspace_id}/organizations/{id} Changes an organization's name, description, client ids or custom fields; a field left out keeps its value. Needs organization.write at the organization. A deleted organization can be updated. To change its parent, move it.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PATCH \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000103" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "psa_client_id": "10063" }'$body = @{ psa_client_id = "10063"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000103" ` -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/organizations/0a9e0000-0000-4000-8000-000000000103" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "psa_client_id": "10063", },)response.raise_for_status(){ "message": "organization updated", "id": "0a9e0000-0000-4000-8000-000000000103"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
organization.write
Needs organization.write. organization.write applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe organization's id.
Request body
No field is required. Send no body to accept the defaults.
namestringThe new name. 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
rmm_client_id string or nullThe new RMM client id, cleaned as every name is. Agent installs that pass this id land here. null or an empty string clears it.
left out keeps · null clears · empty string clears
psa_client_id string or nullThe new PSA client id, cleaned as every name is. 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, or the body names parent_id: move the organization instead.NoAPP_API_ERR_PARAMETER_TOO_LONG name is longer than 128 characters, description longer than 2048, or a client id longer than 256 characters once cleaned.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe object does not exist, is in another workspace or is outside your reach, 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 organization
/workspaces/{workspace_id}/organizations/{id} Marks an organization deleted. It must be empty: no live agent or ingest key in it or below it, and no live organization below it. Needs organization.delete at the organization. Deleting a deleted organization 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/organizations/0a9e0000-0000-4000-8000-000000000104" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104" ` -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/organizations/0a9e0000-0000-4000-8000-000000000104" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "organization deleted", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
organization.delete
Needs organization.delete. organization.delete applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe organization'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 object does not exist, is in another workspace or is outside your reach, 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_DELETE_ORG_NOT_EMPTY A live agent, ingest key or organization is in it or below it.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Restore a deleted organization
/workspaces/{workspace_id}/organizations/{id}/restore Restores a deleted organization whose parent is live. Needs organization.delete at the organization. Restoring a live organization 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/organizations/0a9e0000-0000-4000-8000-000000000104/restore" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000104/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/organizations/0a9e0000-0000-4000-8000-000000000104/restore" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "organization restored", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
organization.delete
Needs organization.delete. organization.delete applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe organization'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 object does not exist, is in another workspace or is outside your reach, 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 parent is deleted.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Check a client id
/workspaces/{workspace_id}/organizations/client-id-check Returns how many organizations in the workspace record an RMM or PSA client id, live and deleted, and which of them you can see. Send rmm_client_id or psa_client_id, not both. The counts include organizations you cannot see. It changes nothing.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/client-id-check" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "privilege_organization_id": "0a9e0000-0000-4000-8000-000000000101", "rmm_client_id": "LAKESIDE-01" }'$body = @{ privilege_organization_id = "0a9e0000-0000-4000-8000-000000000101" rmm_client_id = "LAKESIDE-01"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/client-id-check" ` -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/organizations/client-id-check" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "privilege_organization_id": "0a9e0000-0000-4000-8000-000000000101", "rmm_client_id": "LAKESIDE-01", },)response.raise_for_status(){ "message": "client id checked", "live_count": 1, "deleted_count": 0, "visible_matches": [ { "id": "0a9e0000-0000-4000-8000-000000000101", "name": "Lakeside Clinic", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101" ], "deleted": false } ]}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
- any one of
organization.createorganization.write
Needs any one of organization.create or organization.write. organization.create applies at each organization a grant covers and every organization below it. organization.write applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
Request body
No field is required. Send no body to accept the defaults.
rmm_client_id string or nullThe RMM client id to look for, matched once cleaned as every name is, ignoring case. Send this or psa_client_id, not both.
psa_client_id string or nullThe PSA client id to look for, matched once cleaned as every name is, ignoring case. Send this or rmm_client_id, not both.
exclude_organization_id uuid or nullAn organization to leave out of the response, such as the one being edited.
privilege_organization_id uuid or nullThe organization you are creating under or editing: you need organization.create or organization.write there. Left out, you need one of them over every organization.
Response 200
live_count integerrequiredHow many live organizations in the workspace record the id, ones you cannot see included and exclude_organization_id left out.
deleted_count integerrequiredHow many deleted organizations in the workspace record the id, ones you cannot see included and exclude_organization_id left out.
visible_matches array of ClientIDMatchrequiredThe organizations recording the id that you can see, deleted ones included.
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 Neither rmm_client_id nor psa_client_id is sent, or the one sent is empty.NoAPP_API_ERR_PARAMETER_TOO_LONG The client id is longer than 256 characters once cleaned.NoAPP_API_ERR_BAD_PARAMETERS Both rmm_client_id and psa_client_id are sent; parameter names psa_client_id.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeYou hold neither organization.create nor organization.write at privilege_organization_id. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS token_scopeno_privilegeThere is no privilege_organization_id and you hold neither privilege over every organization.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Move an organization
/workspaces/{workspace_id}/organizations/{id}/move Moves an organization, with everything below it, under parent_id. Needs organization.move at its current parent, or over every organization for a top-level one, and at the new parent. An organization cannot move under itself or anything below it, and a live one cannot move under a deleted one. Another move that lands while this one runs makes it return 400 naming parent_id: read the tree again before choosing. An organization created while it runs makes it return 409: send the same call again. Neither moves anything. 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/organizations/0a9e0000-0000-4000-8000-000000000102/move" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "parent_id": "0a9e0000-0000-4000-8000-000000000103" }'$body = @{ parent_id = "0a9e0000-0000-4000-8000-000000000103"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102/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/organizations/0a9e0000-0000-4000-8000-000000000102/move" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "parent_id": "0a9e0000-0000-4000-8000-000000000103", },)response.raise_for_status(){ "message": "organization moved", "cache_clear_status": "ok"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
organization.move
Needs organization.move at the organization it is in now and organization.move at the organization it moves to. organization.move applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe organization's id.
Request body
parent_id uuidrequiredThe organization to move it under. Moving needs organization.move at the organization's current parent and 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 parent_id is left out.NoAPP_API_ERR_BAD_PARAMETERS parent_id is not a UUID, is the organization itself or below it, is deleted while the organization is live, or would make the tree deeper than 25 levels.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_scopeno_privilegeThe organization or the new parent does not exist or is outside your reach, or you do not hold organization.move at the organization's parent and at the new one. The same refusal comes when the path names a workspace other than the token's own.No409APP_API_ERR_CONFLICT Another move landed after this call read the tree, and the organization is no longer where the call read it or the new place now breaks one of the rules above; or an organization created in the workspace while the move ran collided with it. Nothing moved: read the organizations again before sending it again.Read first413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.