Key Configuration

A MASTER_API_KEY can be specified as part of the Admin Configuration. We recommend using an online UUID generator.

#Windows SET MASTER_API_KEY=ef003741-bc43-467f-b9ba-bd0d85e38441 #Linux export MASTER_API_KEY=ef003741-bc43-467f-b9ba-bd0d85e38441

API REST Calls

CURL Examples

The simplest example is a call for which no authentication is required. For example:

$ curl http://localhost:8080/api/admin/serverinfo -s {"license":"Pulse Pro License: pro - 3 users expires 2026-03-14","licensePro":true,"licenseDaysLeft":369,"licenseUser":"pro","version":"3.14","licensedUsers":3}

Fetching CSV SQL Query Results

To authenticate calls as using HTTP basic authentication either:

• Pass the username:password of a selected user
• Pass the username api_key with the password MASTER_API_KEY as set in Admin Configuration

$curl 'http://admin:pass@localhost:8080/api/a.csv/DEMODB' -X POST --data-raw 'SELECT NOW() AS N,RAND() AS r,((USER)) as u;' -s N,R,U 2025-03-09 11:39:04.85726,0.820602037895467,admin $curl 'http://api_key:ef003741-bc43-467f-b9ba-bd0d85e38441@localhost:8080/api/a.csv/DEMODB' -X POST --data-raw 'SELECT NOW() AS N,RAND() AS r,((USER)) as u;' -s N,R,U 2025-03-09 11:40:26.182558,0.38069302229415924,admin $ curl 'http://localhost:8080/api/a.csv/DEMODB' --data-raw 'SELECT NOW() AS N,RAND() AS r,((USER)) as u;' -s -u api_key:ef003741-bc43-467f-b9ba-bd0d85e38441 N,R,U 2025-03-09 11:41:04.078449,0.33419673954684215,admin

Creating Users via API

Server administrators can provision users via REST. Authenticate as an existing admin user (admin:pass) or use the api_key:MASTER_API_KEY mechanism shown above.

Action	url	Method	Content Type
Create user	/api/user/admin	POST	application/json
Update user	/api/user/admin	PUT	application/json
Delete user	/api/user/{id}	DELETE
List all users	/api/user/private	GET

Supported JSON fields when creating a user:

• name (required) - lowercase letters and digits only, 3-30 characters.
• password (required) - at least 7 characters. Hashed before storage; never returned to the client.
• email (optional) - must be unique if specified.
• roleType (optional, defaults to EDITOR) - one of ADMIN, EDITOR, or VIEWER.

$ curl 'http://admin:pass@localhost:8080/api/user/admin' -X POST --data-raw '{"name":"alice","email":"alice@example.com","password":"hunter27","roleType":"EDITOR"}' -H 'Content-Type: application/json' -s {"id":11,"name":"alice","dateCreated":1741610000000,"dateUpdated":1741610000000,"password":null,"roleType":"EDITOR","email":"alice@example.com","emailVerified":false,"emailCode":"","starCount":0,"origin":"admin"} $ curl 'http://api_key:ef003741-bc43-467f-b9ba-bd0d85e38441@localhost:8080/api/user/admin' -X POST --data-raw '{"name":"bob","password":"hunter27","roleType":"VIEWER"}' -H 'Content-Type: application/json' -s {"id":12,"name":"bob","dateCreated":1741610000100,"dateUpdated":1741610000100,"password":null,"roleType":"VIEWER","email":null,"emailVerified":false,"emailCode":"","starCount":0,"origin":"admin"} $ curl 'http://admin:pass@localhost:8080/api/user/12' -X DELETE -s

Mirroring Permissions via API

The POST /api/admin/sync-permissions endpoint accepts a flat list of (user, team, role) triples and idempotently ensures each user, team, and membership exists. Designed for enterprise SSO deployments to mirror their permissions source-of-truth (LDAP, SCIM, custom HR system, etc.) into Pulse on a schedule.

Users created by this endpoint are stored with the sentinel password constant User.EXTERNAL_AUTH_PASSWORD (currently the literal "EXTERNALAUTHENTICATION") — the same convention used for all SSO-authenticated users. They cannot sign in with a Pulse-managed password; authentication is delegated to your SSO / trusted-header layer.

Action	URL	Method	Content Type
Sync permissions	/api/admin/sync-permissions	POST	application/json

Request body is a JSON array. Every row must have all three fields:

• user — required. Used as the canonical user name. Stored as-provided (case-sensitive, not whitespace-trimmed) so the caller should send pre-normalized lowercase names to match existing Pulse usernames.
• team — required. Same conventions as user.
• role — required. Case-insensitive. Must resolve to VIEWER or EDITOR. Any other value (including ADMIN, NONE, or unknown strings) is counted as an error and the rest of the batch continues.

Response is a JSON object with four counts:

• created — new memberships (possibly with new users/teams).
• updated — existing memberships whose role changed (either direction).
• noop — existing memberships unchanged.
• errors — rows that failed validation. Per-row reasons are in the server log.

$ curl 'http://localhost:8080/api/admin/sync-permissions' \ -X POST \ -u api_key:ef003741-bc43-467f-b9ba-bd0d85e38441 \ -H 'Content-Type: application/json' \ --data-raw '[ {"user":"alice","team":"trading","role":"EDITOR"}, {"user":"alice","team":"risk","role":"VIEWER"}, {"user":"bob","team":"trading","role":"VIEWER"} ]' -s {"created":3,"updated":0,"noop":0,"errors":0}

Behaviour summary:

• Users, teams, and memberships are created if missing.
• An existing membership's role is updated to the incoming value, including downgrades (EDITOR → VIEWER).
• A user's global role is bumped from VIEWER to EDITOR if any row grants them EDITOR. ADMIN users are never modified. Global role is never downgraded by this endpoint.
• Memberships present in Pulse but absent from the batch are not removed; they are logged at WARN as sync-permissions would-delete user=… team=… role=… so operators can spot drift.