# Quickstart

This guide gets you started with the API to query a list of your client organizations.

## 1. Create a token

In the app, open **Workspace Settings**, then **Access**, and under **API tokens** choose **New Token**.

- **Name:** something you will recognize in the audit log, such as "API quickstart".
- **Owner:** **You**. This makes a personal token, which can do what you can do.
- **Access limits:** tick the box and choose only **Read workspace information**. The token then carries the scope `workspace:read` and cannot change anything.
- **Expires:** 30 days is enough for a trial.

Copy the secret when it is shown.
It is shown once.

Put it in an environment variable to keep it out of your code and your shell history:

```bash
export SPARKLOGS_TOKEN='sl_...'
```

In PowerShell:

```powershell
$env:SPARKLOGS_TOKEN = 'sl_...'
```

Each sample on these pages has tabs for curl, PowerShell and Python. The Markdown copies of the pages show curl only.
The sample data is made up, and its dates are written as if today were 10 November 2026.
In Windows PowerShell, `curl` is an alias for another command and does not accept curl's options: use the PowerShell sample, or type `curl.exe`.

Windows PowerShell 5.1 needs two more things.
It may need TLS 1.2 switched on first: `[Net.ServicePointManager]::SecurityProtocol = 'Tls12'`.
`Invoke-RestMethod` throws on a 4xx or 5xx response. Read the status, the body and the `Retry-After` header from the error.
[Retries](https://sparklogs.com/docs/api/retries.md) has a function that does this.

## 2. Check the token

**`GET /credential`** [Read credential metadata](https://sparklogs.com/docs/api/reference/credential.md#read-credential)

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/credential" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "credential": {
    "kind": "user_key",
    "credential_id": "4b1d0000-0000-4000-8000-000000000802",
    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
    "region_id": "us-central",
    "scope_restriction": "listed",
    "scopes": [
      "workspace:read"
    ],
    "expires_at": "2026-12-10T16:00:00Z"
  },
  "message": "credential retrieved"
}
```

The response lists the token's kind, the workspace it belongs to and its scopes.
Note `workspace_id`: every other path needs it.

A 401 means the secret was not copied whole, or the token has been revoked.
After repeated calls with a token that does not work, the API answers 429 instead of 401.
Fix the token first: once the failing calls stop, the 429 clears within seconds.

## 3. List your organizations

**`GET /workspaces/{workspace_id}/organizations`** [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

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

Replace the workspace id in the path with yours.
The response lists your organizations. `next_cursor` is null when there are no more pages.

Each organization has an `id`, its `parent_id`, a `name`, and the ids your RMM and PSA use for the client.

## Where to go next

- [Concepts](https://sparklogs.com/docs/api/concepts.md): organizations, agents, grants and tokens.
- [Example use cases](https://sparklogs.com/docs/api/use-cases.md): common automations one API call at a time, such as onboarding a client from your PSA.
- For anything that changes the workspace, create a workspace token with the scopes your automation needs. [Scopes](https://sparklogs.com/docs/api/scopes.md) lists them.

---

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