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:readand 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:
export SPARKLOGS_TOKEN='sl_...'
In 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 has a function that does this.
2. Check the token
/credential - curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/credential" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/credential" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/credential" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" ` -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/organizations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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: organizations, agents, grants and tokens.
- Example use cases: 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 lists them.