API reference

Everything a workspace token can do: 77 operations. The same list is behind the MCP server and the command line tool, so all three always match. A machine-readable copy is at /api/v1/openapi.json.

Making a request #

Every operation is a POST to https://clearsaga.com/api/v1/<name> with a JSON object as its body, reads included. No body means an empty object. The answer is a JSON object with status 200.

Create a token in the dashboard under Settings, Agent access, and send it in the Authorization header. That header is the only place a token is read from: never put one in a web address.

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

Start with sites.list: every operation about one site needs a siteId, and the ids come from there. Times in answers are milliseconds since 1970 UTC. Dates you send are YYYY-MM-DD in the time zone of the site.

Tokens #

A token belongs to one workspace and has one or both of two permissions.

• Read: list the sites of the workspace and read every report, revenue included.
• Write: Create, change and delete funnels, campaign links, conversion goals, chart notes, saved segments and alert rules. Create and change store costs. Includes Read.

A token stops working when it is revoked, and when the person who created it leaves the workspace, is removed or becomes a Viewer. The API remembers a token for up to 60 seconds, so a change like that can take that long to reach it. "Last used" on the Agent access page is approximate: it is written at most every 5 minutes.

Every change made with a token is recorded with the name of the token and shown under Settings, Agent access. Reads are not recorded.

A delete removes for good and cannot be undone. It is recorded with the name of what was removed. Only the definition goes, and with an alert rule its delivery log: no recorded visit, event or order is touched.

What a token can never do #

• See or change another workspace. A token belongs to exactly one.
• Use a share link or the public demo in place of a site id.
• Export CSV files.
• Create, list or revoke tokens.
• Invite, remove or change members.
• Change the plan or anything about billing.
• Create, rename, reset or delete a site.
• Change tracking options, exclusions, revenue settings or notification settings.
• Enable, change or revoke share links or embed widgets.
• Rename or delete a preset conversion goal.
• Record an order.
• Connect a store or replace its secret.
• Read anything that names a person. Visitor profiles, where a site switched them on, are a random id with a generated name, places, devices and pages.

Dashboard actions that are closed to tokens, and why:

Limits #

• 120 requests per minute per workspace, over all its tokens, counted approximately and per Cloudflare location. Over the limit the answer is 429 with Retry-After: 60.
• 30 attempts per minute from one address with tokens that are not recognised.
• A body of at most 65,536 bytes.
• Lists: limit 1 to 100, offset 0 to 1,000, and offset plus limit at most 1,000. A cursor is the nextCursor of the page before, sent back unchanged.
• No CORS headers are sent. The API is for programs, not for pages in a browser.

Filters #

Reports about one site take a filters object such as { "country": "us", "path.has": "pricing" }. A plain key means "is", a key ending in .not means "is not" and a key ending in .has means "contains". Filters are joined with AND. At most 10 keys, of which at most 3 may end in .has. A key that is not in this table is refused.

Errors #

Every error is { "error": { "code", "message" } }, sometimes with detail, fields or reason. Decide on code, which is stable. message is one sentence that says what to change.

When the workspace is locked #

The dashboards of a workspace lock when its monthly allowance is used up, and when its trial or plan has ended. While they are locked, every operation that reads a report answers 402 with the code workspace_locked and a reason of limit, grace or expired. The message says what lifts the lock.

Operations that list definitions, such as funnels, goals or saved segments, keep answering, and so do the operations that change them. The page of each read operation says which of the two it does. Plans, usage and limits explains the lock itself.

All operations #