# 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](https://sparklogs.com/docs/api/reference/agents.md), [Ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md), [Registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md)

Forms a tree

Ids: uuid.

- `GET /workspaces/{workspace_id}/organizations` [List organizations](#list-organizations)
- `GET /workspaces/{workspace_id}/organizations/{id}` [Read an organization](#read-organization)
- `POST /workspaces/{workspace_id}/organizations` [Create an organization](#create-organization)
- `PATCH /workspaces/{workspace_id}/organizations/{id}` [Update an organization](#update-organization)
- `DELETE /workspaces/{workspace_id}/organizations/{id}` [Delete an organization](#delete-organization)
- `POST /workspaces/{workspace_id}/organizations/{id}/restore` [Restore a deleted organization](#restore-organization)
- `POST /workspaces/{workspace_id}/organizations/client-id-check` [Check a client id](#check-client-id)
- `POST /workspaces/{workspace_id}/organizations/{id}/move` [Move an organization](#move-organization)

## 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.

- `id` (uuid): The organization's id.
- `parent_id` (uuid or null): The parent organization's id; null for a top-level organization.
- `path` (array of uuid or null): The ids from the top-level organization down to this one, ending with its own id.
- `name` (string): The organization's name.
- `description` (string or null): The organization's description.
- `rmm_client_id` (string or null): The id your RMM uses for this client. Not unique: several organizations may record the same id.
- `psa_client_id` (string or null): The id your PSA uses for this client. Not unique: several organizations may record the same id.
- `created_at` (date-time): When the organization was created.
- `updated_at` (date-time): When 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 null): When the organization was deleted; null while it is live.
- `custom_fields` (map of any or null): Custom 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

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

Preview

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.

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

### Query parameters

- `id` (array of string): Only the organizations with these ids. A comma-separated list of at most 100 ids matches any of them.
- `parent_id` (uuid): Only the direct children of this organization.
- `root_id` (uuid): Only this organization and every organization below it.
- `name` (string): Only 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` (string): Only 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` (string): Only organizations recording this PSA client id. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
- `deleted` (one of the values below): Which organizations to list, by whether they are deleted.
  Default: `exclude`
  - `exclude`: Live organizations only. The default.
  - `include`: Live and deleted organizations.
  - `only`: Deleted organizations only.
- `updated_since` (date-time): Only organizations changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.
- `limit` (integer): How many organizations a page holds: 1 to 5000, 1000 by default.
  Default: `1000` · 1 to 5000
- `cursor` (string): The `next_cursor` of the previous page, with the same filters.
- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `parent_id`, `path`, `name`, `description`, `rmm_client_id`, `psa_client_id`, `created_at`, `updated_at`, `deleted_at`

Sent only when named in `fields`: `custom_fields`

### Response (200)

- `organizations` (array of Organization, required): The organizations on this page.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor` for the next page.
- `watermark` (date-time, required): Pass it as `updated_since` on your next sync.
- `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` | 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. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_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. | 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 `organization.read`. The same refusal comes when the path names a workspace other than the token's own. | 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 an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

List the organizations a read-only personal token can see

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

Response (200)

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

## Read an organization

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/organizations/{id}`

Preview

Returns one organization you can see, deleted or not. One you cannot see returns 404, as one that does not exist does.

### 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` (uuid, required): The workspace's id.
- `id` (uuid, required): The organization'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`, `parent_id`, `path`, `name`, `description`, `rmm_client_id`, `psa_client_id`, `created_at`, `updated_at`, `deleted_at`

Sent only when named in `fields`: `custom_fields`

### Response (200)

- `organization` (Organization, required): The organization.
- `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 |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `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 `organization.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such organization, or one you cannot see. | 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

Read an organization

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

Response (200)

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

## Create an organization

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

Preview

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.

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

### Request body

- `parent_id` (uuid or null): The organization to create it under; leave it out to create a top-level organization.
- `name` (string, required): The organization's name. Cleaned, as every name is. Required.
  at most 128 characters
- `description` (string or null): The organization's description.
  at most 2048 characters
- `rmm_client_id` (string or null): The 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.
  at most 256 characters
- `psa_client_id` (string or null): The id your PSA uses for this client, cleaned as every name is. Not unique: other organizations may record the same id.
  at most 256 characters

### Response (200)

- `id` (uuid, required): The new organization's id.
- `cache_clear_status` (one of the values below, required): How far the new organization got into every region's cache.
  - `ok`: Every region's cache has the organization.
  - `failed`: A 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.
  - `disabled`: This 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 null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `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_MISSING_PARAMETER` | `name` is left out or empty. | No |
| 400 | `APP_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. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `parent_id` is not a UUID, names a deleted organization, or would make the tree deeper than 25 levels. | 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_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | You 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. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS` (cause `token_scope` or `no_privilege`) | There is no `parent_id` and you do not hold `organization.create` over every organization. | 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

Create Finance, a site of Lakeside Clinic, under it

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

Response (200)

```json
{
  "message": "organization created",
  "id": "0a9e0000-0000-4000-8000-000000000102",
  "cache_clear_status": "ok"
}
```

## Update an organization

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

Preview

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.

### 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` (uuid, required): The workspace's id.
- `id` (uuid, required): The organization'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
- `rmm_client_id` (string or null): The 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
  at most 256 characters
- `psa_client_id` (string or null): The new PSA client id, cleaned as every name is. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears
  at most 256 characters
- `custom_fields` (map of any or null): Changes 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)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This 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 null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `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` | `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, or the body names `parent_id`: move the organization instead. | No |
| 400 | `APP_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. | 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_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The 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. | 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

Record an organization's PSA client id

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

Response (200)

```json
{
  "message": "organization updated",
  "id": "0a9e0000-0000-4000-8000-000000000103"
}
```

## Delete an organization

`DELETE https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/organizations/{id}`

Preview · Destructive

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.

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

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This 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 null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `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, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_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`. | 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_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The 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. | No |
| 409 | `APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY` | A live agent, ingest key or organization is in it or below it. | 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

Delete an empty organization

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

Response (200)

```json
{
  "message": "organization deleted",
  "cache_clear_status": "ok"
}
```

## Restore a deleted organization

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/organizations/{id}/restore`

Preview

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.

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

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This 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 null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `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` | `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`, or names a field: the call takes none. | 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_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The 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. | No |
| 409 | `APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED` | Its parent is deleted. | 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

Restore a deleted organization

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

Response (200)

```json
{
  "message": "organization restored",
  "cache_clear_status": "ok"
}
```

## Check a client id

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/organizations/client-id-check`

Preview

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.

### Access

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

### Request body

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

- `rmm_client_id` (string or null): The RMM client id to look for, matched once cleaned as every name is, ignoring case. Send this or `psa_client_id`, not both.
  at most 256 characters
- `psa_client_id` (string or null): The PSA client id to look for, matched once cleaned as every name is, ignoring case. Send this or `rmm_client_id`, not both.
  at most 256 characters
- `exclude_organization_id` (uuid or null): An organization to leave out of the response, such as the one being edited.
- `privilege_organization_id` (uuid or null): The 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` (integer, required): How many live organizations in the workspace record the id, ones you cannot see included and `exclude_organization_id` left out.
- `deleted_count` (integer, required): How many deleted organizations in the workspace record the id, ones you cannot see included and `exclude_organization_id` left out.
- `visible_matches` (array of ClientIDMatch, required): The organizations recording the id that you can see, deleted ones included.
- `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_MISSING_PARAMETER` | Neither `rmm_client_id` nor `psa_client_id` is sent, or the one sent is empty. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | The client id is longer than 256 characters once cleaned. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | Both `rmm_client_id` and `psa_client_id` are sent; `parameter` names `psa_client_id`. | 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_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | You 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. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS` (cause `token_scope` or `no_privilege`) | There is no `privilege_organization_id` and you hold neither privilege over every organization. | 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization)

### Example

Check whether an RMM client id is taken

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

Response (200)

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

## Move an organization

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/organizations/{id}/move`

Preview

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.

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

### Request body

- `parent_id` (uuid, required): The 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 null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This 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 null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `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` | `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_MISSING_PARAMETER` | `parent_id` is left out. | No |
| 400 | `APP_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. | 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_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The 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. | No |
| 409 | `APP_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 first |
| 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

- [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)
- [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization)
- [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)
- [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization)
- [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)
- [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization)
- [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id)

### Example

Move Finance under Oakridge Medical

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

Response (200)

```json
{
  "message": "organization moved",
  "cache_clear_status": "ok"
}
```

## ClientIDMatch object

- `id` (uuid, required): The organization's id.
- `name` (string, required): The organization's name.
- `path` (array of uuid or null, required): The ids from the top-level organization down to this one, ending with its own id.
- `deleted` (boolean, required): Whether the organization is deleted: true for a deleted one, false for a live one.

---

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