Skip to content

API reference Connections

API reference

Connections

The API operations about connections, each with its input, its output and an example.

The operations about connections. Each one is a POST with a JSON object as its body: Making a request has the rules they share.

Ad platform connections #

POST /api/v1/connections.list · Read

The ad platform accounts connected to one site, oldest first: for each, the platform, the account name, its status, when spend was last synced and the last error. Get the siteId from sites.list first. Spend is synced from each active connection every hour. A status of needs_reauth means the sign-in was revoked or expired and a person must sign in again in the dashboard; error means the last syncs failed and lastError says why; paused connections are not synced. lastSyncAt is an ISO 8601 time in UTC, or null before the first sync. The answer never carries a sign-in token. It holds an empty list for a site with no connection, and it still answers while the workspace's dashboards are locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

Input #

Field Type Required Description
siteId string required The site id, from sites.list.

Output #

Field Type Present Description
connections array of object always The ad accounts connected to the site, oldest first: id, platform, accountName, status, lastSyncAt (ISO time or null) and lastError (text or null). No sign-in token is ever included.

Example #

curl -s -X POST https://clearsaga.com/api/v1/connections.list \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"site_abc123def456"}'

Run clearsaga help connections list for one flag per field.