# Workspaces

A workspace holds your organizations, agents, people and settings; read it and change its name, onboarding and ingest policy.

Contains: [Credential](https://sparklogs.com/docs/api/reference/credential.md), [Agents](https://sparklogs.com/docs/api/reference/agents.md), [Ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md)

Ids: uuid.

- `GET /workspaces/{workspace_id}` [Read a workspace](#read-workspace)
- `PATCH /workspaces/{workspace_id}` [Update a workspace](#update-workspace)
- `PATCH /workspaces/{workspace_id}/onboarding` [Update onboarding](#update-onboarding)
- `PATCH /workspaces/{workspace_id}/ingest-policy` [Update the ingest policy](#update-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.

- `id` (uuid): The workspace's id.
- `name` (string): The workspace's name.
- `description` (string or null): The workspace's description.
- `region` (Region): Where the workspace's data lives.
- `plan` (ServicePlan): The workspace's service plan.
- `data_initialized` (boolean): Whether the workspace's data storage is set up.
- `retention_hours` (integer): How long log data is kept, in hours.
- `trial_expires_at` (date-time or null): When the workspace's trial ends; null when it has none.
- `app_analytics_provisioned` (boolean): Whether App Analytics is set up.
- `deleted_at` (date-time or null): When the workspace was deleted; null while it is live.
- `updated_at` (date-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.
- `usage` (Usage 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.
- `storage` (Storage 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.
- `settings` (any 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_statuses` (array of JobStatus or null): The latest run of each of the workspace's background jobs.
- `agent_rollout_ring` (string or null): Which agent update ring the workspace's agents follow: `canary`, `early_access` or `stable`.

## Read a workspace

`GET https://engine.sparklogs.app/app-api/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.

### 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` (uuid, required): The workspace's id.

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `name`, `description`, `region`, `plan`, `data_initialized`, `retention_hours`, `trial_expires_at`, `app_analytics_provisioned`, `deleted_at`, `updated_at`

Sent only when named in `fields`: `usage`, `storage`, `settings`, `job_statuses`, `agent_rollout_ring`

### Response (200)

- `workspace` (Workspace, required): The workspace.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `workspace.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | `fields` names `usage` without `ingestion.read`, or `storage` without `archive.config.read`, across the whole workspace. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Update a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#update-workspace)
- [Update onboarding](https://sparklogs.com/docs/api/reference/workspaces.md#update-onboarding)
- [Update the ingest policy](https://sparklogs.com/docs/api/reference/workspaces.md#update-ingest-policy)

### Example

Read the workspace

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

Response (200)

```json
{
  "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"
  }
}
```

## Update a workspace

`PATCH https://engine.sparklogs.app/app-api/workspaces/{workspace_id}`

Preview

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

### 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` (uuid, required): The workspace's id.

### Request body

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

- `name` (string): 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
- `description` (string 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)

- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_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`. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `name` is empty. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `name` is longer than 128 characters, or `description` longer than 2048. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `workspace.write`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#read-workspace)
- [Update onboarding](https://sparklogs.com/docs/api/reference/workspaces.md#update-onboarding)
- [Update the ingest policy](https://sparklogs.com/docs/api/reference/workspaces.md#update-ingest-policy)

### Example

Change the workspace's description

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

Response (200)

```json
{
  "message": "workspace updated"
}
```

## Update onboarding

`PATCH https://engine.sparklogs.app/app-api/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`.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `workspace.read`, `organization.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` (uuid, required): The workspace's id.

### Request body

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

- `onboarding` (OnboardingPatch): 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)

- `onboarding` (map of any or null, required): The stored onboarding state after the change.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_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`. | No |
| 400 | `APP_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. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You 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 |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#read-workspace)
- [Update a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#update-workspace)
- [Update the ingest policy](https://sparklogs.com/docs/api/reference/workspaces.md#update-ingest-policy)

### Example

Dismiss the onboarding guide

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

Response (200)

```json
{
  "message": "onboarding saved",
  "onboarding": {
    "dismissed_at": "2026-11-10T09:00:00Z"
  }
}
```

## Update the ingest policy

`PATCH https://engine.sparklogs.app/app-api/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`.

### 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` (uuid, required): The workspace's id.

### Request body

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

- `ingest_policy` (IngestPolicyPatch): 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_policy` (map of any or null, required): The stored ingest policy after the change.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_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`. | No |
| 400 | `APP_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. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `workspace.write`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#read-workspace)
- [Update a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#update-workspace)
- [Update onboarding](https://sparklogs.com/docs/api/reference/workspaces.md#update-onboarding)

### Example

Cap uncurated events at warning

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

Response (200)

```json
{
  "message": "ingest policy saved",
  "ingest_policy": {
    "uncurated_max_severity": 13
  }
}
```

## Region object

A region is a place a workspace's data can live, with the addresses its data is sent to and queried at.

- `id` (string): The region's id.
- `name` (string): The region's name.
- `sort_order` (integer): Where the region sorts in a list of regions.
- `ingest_uri` (string): The address agents send this region's log data to.
- `query_uri` (string): The address this region's data is queried at.
- `bigquery_location` (string or null): The BigQuery location this region's workspace datasets are created in, such as `US`. list-regions returns it only when named in `fields`; a workspace's region always carries it.

## ServicePlan object

- `id` (string, required): The plan's id.
- `name` (string, required): The plan's name.
- `description` (string or null, required): The plan's description.
- `sort_order` (integer, required): Where the plan sorts in a list of plans.
- `data_engine_id` (string, required): The engine the plan stores and queries data with.
- `is_billable` (boolean, required): Whether the plan is billed.
- `max_retention_hours` (integer, required): The longest retention the plan allows, in hours.
- `self_hosted_querying` (boolean, required): Whether queries run in your own cloud project.
- `allow_custom_query_scanned_limit` (boolean, required): Whether the workspace may set its own limit on data scanned per query.

## Usage object

- `ingest_quota_bytes` (integer, required): The workspace's ingest quota, in bytes.
- `ingested_this_month_bytes` (integer, required): The most ingested so far this month, in bytes. It is sampled, so it can trail the true figure by a few minutes of ingest.
- `custom_query_scanned_limit_mib` (integer or null, required): The workspace's own limit on data scanned per query, in MiB; null for the plan's.

## Storage object

- `gcp_project_id` (string or null, required): The Google Cloud project holding the workspace's data.
- `gcp_bigquery_dataset` (string or null, required): The BigQuery dataset holding the workspace's data.
- `gcp_archive_bucket` (string or null, required): The Cloud Storage bucket the workspace archives to.
- `gcp_archive_bucket_prefix` (string or null, required): The path inside the archive bucket.
- `gcp_archive_bucket_verified_at` (date-time or null, required): When SparkLogs last confirmed it can write to the archive bucket.

## JobStatus object

- `job_type` (string, required): The kind of job.
- `last_job_id` (string, required): The id of the job's latest run.
- `summary` (string or null, required): A one-line account of the latest run.
- `details` (string or null, required): What the latest run did, as text. Its contents are not part of the API contract and may change.
- `healthy` (boolean, required): Whether the latest run left the job healthy.
- `severity` (integer, required): How serious the latest run's outcome is, on the log severity scale: 9 ok, 13 warning, 17 error, 21 fatal.
- `status` (string, required): Where the latest run stands.
- `started_at` (date-time, required): When the latest run started.
- `finished_at` (date-time or null, required): When the latest run finished.
- `extra_data` (any or null, required): More about the latest run, as an object. Its contents are not part of the API contract and may change.

## OnboardingPatch object

- `persona` (one of the values below, or null): Who the workspace is for.
  - `msp_it`: An MSP or IT team.
  - `game_app`: A game or app developer.
  - `sre_dev`: An SRE or developer.
- `wizard_status` (one of the values below, or null): Where the setup wizard stands.
  - `not_started`: Not started.
  - `in_progress`: In progress.
  - `automated_complete`: The automated steps are done.
  - `completed`: Completed.
  - `dismissed`: Dismissed.
- `wizard_version` (integer): The setup wizard's version. `null` returns 400.
  left out keeps · `null` is refused
- `wizard_automated_completed_at` (date-time or null): When the wizard's automated steps finished. `null` clears it.
  left out keeps · `null` clears
- `setup_mode` (one of the values below, or null): Which setup the wizard follows.
  - `recommended`: The recommended setup.
  - `advanced`: The advanced setup.
- `manual_tasks` (map of any or null): By task id, each an object of `completed_at` and `skipped_at`, a time or null to clear it.
- `dismissed_at` (date-time or null): When onboarding was dismissed. `null` clears it.
  left out keeps · `null` clears
- `wizard_state` (map of any or null): The wizard's own state, an object.
- `wizard_data` (map of any or null): The wizard's own lasting facts, an object.

## IngestPolicyPatch object

- `uncurated_max_severity` (integer or null): The highest severity an uncurated event is stored at: a higher one is lowered to it. Clearing it removes the cap. `null` clears it.
  left out keeps · `null` clears
  1 to 24
- `uncurated_syslog_max_severity` (integer or null): The same cap for uncurated syslog events. `null` clears it.
  left out keeps · `null` clears
  1 to 24

---

Source: <https://sparklogs.com/docs/api/reference/workspaces>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
