Skip to content

API reference Sites

API reference

Sites

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

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

Site details #

POST /api/v1/sites.get · Read

What to know about one site before asking for its numbers: its name, domain and time zone, the enabled conversion goals, and what it has ever recorded (a first hit, orders, campaign tags, web vitals, pages that were not found). Get the siteId from sites.list first. Use it to learn the time zone that from and to dates are days in, the currency revenue is reported in, the goal names the conversion filter takes, and whether a report can have data at all: firstHitAt null means the tracker has not sent a hit yet, hasRevenue false means the revenue operations answer zeros, hasVitals false means performance.report is empty. It holds no visitor numbers and keeps working while the workspace is 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
ref object always How to name this site in the next call. For a token it is always { siteId }; the other two keys belong to shared dashboards and the public demo and never appear.
site object always The site: its id, name, domain and time zone (an IANA name such as Europe/Berlin; every date of a range is a day in this zone). isDemo is true only for the seeded demo site.
workspace object always The workspace the site belongs to, and defaultRange, the period a report covers when range is left out.
capabilities object always What the site records and what this caller may do. firstHitAt is the time of the first recorded hit in milliseconds since 1970 UTC, null while there is none. hasRevenue says whether an order was ever recorded and currency is the main currency of its orders. conversions lists the enabled conversion goals: key is the value the conversion filter takes. campaignsEnabled, has404Tracking and hasVitals say whether campaign tags, "not found" hits and web vitals were ever recorded or are switched on. searchConsole is always disconnected in this version. rawDataFrom is the earliest time detailed data is kept from (null when nothing was trimmed) and storage says whether the site is near its storage limit. mode is member for a token. canEditNotes is true for a token with the Write permission; canManageIntegrations and canExport are always false for a token. remembersVisitors says whether the site has switched on Remember returning visitors, which uses a cookie; when it is false or left out the site counts every visit without a cookie and the visitors operations answer 409 feature_off.

Example #

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

Run clearsaga help sites get for one flag per field.

List sites #

POST /api/v1/sites.list · Read

Lists every site of the workspace the token belongs to: its id, name, domain and when it recorded its first hit. Call this first. Every other site operation needs a siteId, and the ids come from here. A site whose firstEventAt is null has not received a hit yet, so its reports are empty. Takes no input and keeps working while the workspace is locked.

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

Input #

No fields. Send an empty object, or no body.

Output #

Field Type Present Description
rows array of object always One row per site, by name: id (the siteId every site operation takes), name, domain, and firstEventAt, the time of the first recorded hit in milliseconds since 1970 UTC or null while the tracker has not sent one.

Example #

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

Run clearsaga help sites list for one flag per field.