Skip to main content

Workspaces

A workspace holds your organizations, agents, people and settings; read it and change its name, onboarding and 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.

iduuid

The workspace's id.

namestring

The workspace's name.

descriptionstring or null

The workspace's description.

regionRegion

Where the workspace's data lives.

planServicePlan

The workspace's service plan.

data_initializedboolean

Whether the workspace's data storage is set up.

retention_hoursinteger

How long log data is kept, in hours.

trial_expires_atdate-time or null

When the workspace's trial ends; null when it has none.

app_analytics_provisionedboolean

Whether App Analytics is set up.

deleted_atdate-time or null

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

updated_atdate-time

When 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 null

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

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

The 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_statusesarray of JobStatus or null

The latest run of each of the workspace's background jobs.

agent_rollout_ringstring or null

Which agent update ring the workspace's agents follow: canary, early_access or stable.

Read a workspace​

GET/workspaces/{workspace_id}
Preview

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.

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

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_iduuidrequired

The workspace'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: idnamedescriptionregionplandata_initializedretention_hourstrial_expires_atapp_analytics_provisioneddeleted_atupdated_at

Sent only when named in fields: usagestoragesettingsjob_statusesagent_rollout_ring

Response 200

workspaceWorkspacerequired

The workspace.

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
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold workspace.read. The same refusal comes when the path names a workspace other than the token's own.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegefields names usage without ingestion.read, or storage without archive.config.read, across the whole workspace.No

Plus the errors every call can return.

Related

Update a workspace​

PATCH/workspaces/{workspace_id}
Preview

Changes the workspace's name and description; a field left out keeps its value. Needs workspace.write.

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

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_iduuidrequired

The workspace's id.

Request body

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

namestring

The new name. Cleaned, as every name is. 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

Response 200

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_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_PRIVILEGEtoken_scopeno_privilegeYou do not hold workspace.write. 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

Update onboarding​

PATCH/workspaces/{workspace_id}/onboarding
Preview

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.

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

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_iduuidrequired

The workspace's id.

Request body

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

onboardingOnboardingPatch

Changes 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 nullrequired

The stored onboarding state after the change.

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_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_PARAMETERSonboarding 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.No
403APP_API_ERR_NO_PRIVILEGEtoken_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.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Update the ingest policy​

PATCH/workspaces/{workspace_id}/ingest-policy
Preview

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.

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

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_iduuidrequired

The workspace's id.

Request body

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

ingest_policyIngestPolicyPatch

Changes 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_policymap of any or nullrequired

The stored ingest policy after the change.

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_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_PARAMETERSingest_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.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold workspace.write. 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