Workspaces
A workspace holds your organizations, agents, people and settings; read it and change its name, onboarding and ingest policy.
Contains: Credential, Agents, Ingest keys
- GET
Read a workspace/workspaces /{workspace_id} - PATCH
Update a workspace/workspaces /{workspace_id} - PATCH
Update onboarding/workspaces /{workspace_id} /onboarding - PATCH
Update the ingest policy/workspaces /{workspace_id} /ingest-policy
Workspace object
A workspace is one MSP's or IT team's account: its organizations, agents, people, settings and the region its data lives in.
iduuidThe workspace's id.
namestringThe workspace's name.
descriptionstring or nullThe workspace's description.
regionRegionWhere the workspace's data lives.
planServicePlanThe workspace's service plan.
data_initialized booleanWhether the workspace's data storage is set up.
retention_hours integerHow long log data is kept, in hours.
trial_expires_at date-time or nullWhen the workspace's trial ends; null when it has none.
app_analytics_provisioned booleanWhether App Analytics is set up.
deleted_at date-time or nullWhen the workspace was deleted; null while it is live.
updated_at date-timeWhen the workspace's record last changed. Every write to it moves this, SparkLogs' own bookkeeping such as recorded ingest usage included, so it moves without any change to settings.
usageUsage or nullHow much the workspace has ingested against its quota. Needs ingestion.read across the whole workspace: held on part of the organization tree, naming this field returns 403.
storageStorage or nullWhere the workspace's data and archive are stored. Needs archive.config.read across the whole workspace: held on part of the organization tree, naming this field returns 403.
settingsany or nullThe workspace's settings, such as onboarding and ingest_policy, as an object. Its contents are not part of the API contract and may change.
job_statuses array of JobStatus or nullThe latest run of each of the workspace's background jobs.
agent_rollout_ring string or nullWhich agent update ring the workspace's agents follow: canary, early_access or stable.
Read a workspace
/workspaces/{workspace_id} Returns the workspace's settings and state: its name, region, service plan, retention and trial. usage needs ingestion.read and storage needs archive.config.read, each across the whole workspace; naming either in fields without it returns 403.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001" ` -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" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "workspace retrieved", "workspace": { "id": "5e1f0a00-0000-4000-8000-000000000001", "name": "Northwind IT Services", "description": "Managed IT for clinics and small offices", "region": { "id": "us-central", "name": "United States", "sort_order": 1, "ingest_uri": "https://ingest-usc1.engine.sparklogs.app", "query_uri": "https://query-usc1.engine.sparklogs.app", "bigquery_location": "US" }, "plan": { "id": "sparklogs_cloud", "name": "SparkLogs Cloud", "description": null, "sort_order": 10, "data_engine_id": "bigquery", "is_billable": true, "max_retention_hours": 8760, "self_hosted_querying": false, "allow_custom_query_scanned_limit": true }, "data_initialized": true, "retention_hours": 2160, "trial_expires_at": null, "app_analytics_provisioned": false, "deleted_at": null, "updated_at": "2026-11-10T06:00:00Z" }}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
workspace:read- Privilege
workspace.read
Needs workspace.read. Any grant in the workspace carries workspace.read.
Behavior
- Retry
- Safe to send again
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: idnamedescriptionregionplandata_initializedretention_hourstrial_expires_atapp_analytics_provisioneddeleted_atupdated_at
Sent only when named in fields: usagestoragesettingsjob_statusesagent_rollout_ring
Response 200
The workspace.
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.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold workspace.read. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_NO_PRIVILEGE token_scopeno_privilegefields names usage without ingestion.read, or storage without archive.config.read, across the whole workspace.NoPlus the errors every call can return.
Related
Update a workspace
/workspaces/{workspace_id} Changes the workspace's name and description; a field left out keeps its value. Needs workspace.write.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PATCH \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "description": "Managed IT for clinics, dental and accounting offices" }'$body = @{ description = "Managed IT for clinics, dental and accounting offices"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001" ` -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" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "description": "Managed IT for clinics, dental and accounting offices", },)response.raise_for_status(){ "message": "workspace updated"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
workspace.write
Needs workspace.write. workspace.write applies to the workspace itself: a grant over every organization, or over the workspace, carries it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace'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
Response 200
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_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 token_scopeno_privilegeYou do not hold workspace.write. 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 onboarding
/workspaces/{workspace_id}/onboarding Merges changes into the workspace's onboarding state and returns it. Needs workspace.read and organization.write. A merge that leaves the state as it was writes nothing, so a call with no onboarding reads the stored state; read-workspace with fields=settings also returns it in settings.onboarding.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PATCH \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/onboarding" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "onboarding": { "dismissed_at": "2026-11-10T09:00:00Z" } }'$body = @{ onboarding = @{ dismissed_at = "2026-11-10T09:00:00Z" }}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/onboarding" ` -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/onboarding" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "onboarding": { "dismissed_at": "2026-11-10T09:00:00Z", }, },)response.raise_for_status(){ "message": "onboarding saved", "onboarding": { "dismissed_at": "2026-11-10T09:00:00Z" }}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
fleet:write- Privilege
workspace.readorganization.write
Needs workspace.read and organization.write. Any grant in the workspace carries workspace.read. 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.
Request body
No field is required. Send no body to accept the defaults.
onboardingOnboardingPatchChanges to the onboarding state, merged into the stored one: a key left out keeps its value. Left out, nothing changes. null returns 400.
left out keeps · null is refused
Response 200
onboardingmap of any or nullrequiredThe stored onboarding state after the change.
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_BAD_PARAMETERS onboarding is not an object, names a key it does not take, holds a value it does not take, is larger than 16384 bytes, or holds a wizard_state larger than 8192 bytes or a wizard_data larger than 8192 bytes.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold workspace.read, and organization.write over every 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
Update the ingest policy
/workspaces/{workspace_id}/ingest-policy Merges changes into the workspace's ingest policy and returns it. Needs workspace.write. A merge that leaves the policy as it was writes nothing, so a call with no ingest_policy reads the stored policy; read-workspace with fields=settings also returns it in settings.ingest_policy.
- Request
- Response
- curl
- PowerShell
- Python
curl -X PATCH \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-policy" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ingest_policy": { "uncurated_max_severity": 13 } }'$body = @{ ingest_policy = @{ uncurated_max_severity = 13 }}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-policy" ` -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-policy" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "ingest_policy": { "uncurated_max_severity": 13, }, },)response.raise_for_status(){ "message": "ingest policy saved", "ingest_policy": { "uncurated_max_severity": 13 }}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
workspace.write
Needs workspace.write. workspace.write applies to the workspace itself: a grant over every organization, or over the workspace, carries it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
Request body
No field is required. Send no body to accept the defaults.
ingest_policy IngestPolicyPatchChanges to the ingest policy, merged into the stored one: a key left out keeps its value. Left out, nothing changes. null returns 400.
left out keeps · null is refused
Response 200
ingest_policy map of any or nullrequiredThe stored ingest policy after the change.
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_BAD_PARAMETERS ingest_policy is not an object, names a key it does not take, holds a severity that is not a whole number from 1 to 24, or is larger than 4096 bytes.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold workspace.write. 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.