The Clarion API is for systems, not people. A cron job, a data pipeline or an automation platform authenticates with an API key and either writes numbers into the scorecard or reads what the team is working on. There’s no user login involved and no session to keep alive.
Base URL and versioning
https://api.onclarion.com/v1The version is in the path. Within v1, Clarion may add endpoints, optional request fields and response fields. It won’t remove or rename a field, change a field’s type, or change what an existing request does — those changes go in a new version, announced before it ships, with v1 kept running during the overlap. Ignore response fields you don’t recognise.
What you can do
| Endpoint | Scope | What it does |
|---|---|---|
POST /companies/:companyId/metrics/ingest | metrics:write | Write values to one or many metrics |
GET /companies/:companyId/metrics | metrics:read | List metrics with recent values |
GET /companies/:companyId/milestones | milestones:read | List milestones with subtasks |
GET /companies/:companyId/action-items | action_items:read | List action items, open and completed |
POST /metrics/push/:token | none — the URL is the credential | Write one value to one metric |
That’s the whole published surface today. It’s deliberately small: every scope Clarion issues has an endpoint behind it.
Keys that can only do what you allow
API keys are created by owners and admins under Settings → Integrations → API Keys. Each key:
- belongs to one company and can’t reach any other, including a parent agency’s data;
- carries only the scopes you tick, so a reporting script can read metrics without being able to write them;
- is shown once at creation and stored only as a hash;
- shows when it was last used, and can be revoked instantly.
Send it as x-api-key: clr_… or Authorization: Bearer clr_…. See API authentication and scopes.
Writing metric values
The ingest endpoint takes an array of entries, each naming a metric by name or id with a value. Values land on the metric’s current period — day, week or month — and re-sending the same period updates rather than duplicates, so it’s safe on a schedule.
curl -X POST "https://api.onclarion.com/v1/companies/$COMPANY_ID/metrics/ingest" \
-H "x-api-key: clr_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "entries": [ { "metric": "Weekly Revenue", "value": 89306 } ] }'Each entry succeeds or fails on its own. If a name matches metrics on two teams, Clarion refuses to guess: the entry comes back ambiguous_metric with the candidates listed, and nothing is written for it. Full reference: Ingest metric values with the API.
Reading data
The read endpoints return JSON arrays your scripts can filter: metrics with their most recent values, milestones with subtasks, and action items including completed ones. See Read data with the API.
The rest of the platform
- Push URLs — one private URL per metric, for tools that can’t send headers.
- Pull from a URL — Clarion fetches a JSON endpoint on a schedule.
- Webhooks — Clarion calls you when things change.
- Embedded apps — put your own tool in Clarion’s sidebar.
Start with Create API keys.