API
Premely API endpoint reference
Find every Premely API endpoint, HTTP method, required scope and supported operation.
What it is
This reference maps the complete public REST surface under https://api.premely.io.
Why use it
Use it to choose the correct endpoint and least-privilege token scope before you write an integration.
Before you start
- Create an API token with only the scopes needed by your integration.
- Use identifiers returned by Premely. Never guess or reuse identifiers from another workspace.
How to use it
- 1
Choose the resource
Start with the endpoint group that matches the job, such as sites, analytics, goals or exports.
- 2
Grant the required scope
Create or use a token that contains the scope listed for the operation.
- 3
Add authentication and request data
Send the bearer token, path or query identifiers and a JSON body where required.
- 4
Make writes retry-safe
For
POST,PATCHandDELETEoperations, send a UUIDv7Idempotency-Keywhen the endpoint requires it.
Endpoint catalog
All endpoints return JSON unless the export download endpoint returns the selected file format.
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
GET / HEAD | /healthz | Public | Read service activation health without dependency or credential details. |
GET | /v1 | sites:read | Read the bound workspace and safe token metadata. |
GET | /v1/sites | sites:read | List sites with cursor pagination. |
POST | /v1/sites | sites:write | Create a site and reveal its ingestion key once. |
GET | /v1/sites/{siteId} | sites:read | Read one site. |
PATCH | /v1/sites/{siteId} | sites:write | Update display name, timezone or currency. |
POST | /v1/sites/{siteId}/stats/dashboard | analytics:read | Read the canonical dashboard bundle. |
POST | /v1/sites/{siteId}/stats/query | analytics:read | Run a bounded analytics query. |
POST | /v1/sites/{siteId}/revenue/events | revenue:write | Record one immutable revenue event. |
GET | /v1/goals?site_id={siteId} | goals:read | List goals for a site. |
POST | /v1/goals | goals:write | Create an event or page goal. |
GET | /v1/goals/{goalId} | goals:read | Read one goal. |
PATCH | /v1/goals/{goalId} | goals:write | Rename, pause or resume a goal. |
DELETE | /v1/goals/{goalId} | goals:write | Delete a goal. |
GET | /v1/funnels?site_id={siteId} | funnels:read | List funnels for a site. |
POST | /v1/funnels | funnels:write | Create a two-to-four-step funnel. |
GET | /v1/funnels/{funnelId} | funnels:read | Read one funnel. |
PATCH | /v1/funnels/{funnelId} | funnels:write | Update a funnel. |
DELETE | /v1/funnels/{funnelId} | funnels:write | Delete a funnel. |
GET | /v1/alerts?site_id={siteId} | alerts:read | List alerts for a site. |
POST | /v1/alerts | alerts:write | Create a metric alert. |
GET | /v1/alerts/{alertId} | alerts:read | Read one alert. |
PATCH | /v1/alerts/{alertId} | alerts:write | Update, pause or resume an alert. |
DELETE | /v1/alerts/{alertId} | alerts:write | Delete an alert. |
GET | /v1/usage | usage:read | Read entitlement and bounded usage counters. |
GET | /v1/exports?site_id={siteId} | exports:read | List export jobs. |
POST | /v1/exports | exports:write | Queue a CSV, NDJSON or Parquet export for up to 90 days. |
GET | /v1/exports/{exportId} | exports:read | Read export status and its relative download URL when ready. |
GET | /v1/exports/{exportId}/download | exports:read | Download an integrity-checked ready export. |
GET | /v1/audit | audit:read | List workspace audit events. |
GET | /v1/integrations?site_id={siteId} | integrations:read | Read safe integration status without credentials or write controls. |
Cursor pagination
List endpoints accept limit from 1 to 100 and an opaque cursor. The default limit is 50.
curl --get 'https://api.premely.io/v1/sites' \
--header "Authorization: Bearer $PREMELY_API_TOKEN" \
--data-urlencode 'limit=50' \
--data-urlencode 'cursor=CURSOR_FROM_PREVIOUS_RESPONSE'What to expect
Responses stay workspace-bound
Premely authorizes the token and resource inside one workspace before returning data.
One-time credentials are not replayed
A newly created site key is shown only in the first successful response. An idempotent replay returns a safe recovery state without the raw key.