Conventions

The cross-cutting contract every authenticated Clickbase endpoint shares — base URL, headers, the response envelope, money, date ranges, filters, and error codes. Read this once and the per-endpoint pages only need to describe what is unique to them.

Base URL & headers

All endpoints live on the root domain, under the /api prefix:

https://clickbase.so/api

Send these headers on every authenticated request:

See Authentication for how tokens are created and scoped to a team.

curl https://clickbase.so/api/sites \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch('https://clickbase.so/api/sites', {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: 'application/json',
  },
});

import requests

requests.get(
    'https://clickbase.so/api/sites',
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Response envelope

Responses are unwrapped. Clickbase calls JsonResource::withoutWrapping() globally in AppServiceProvider, so:

• A single resource serializes flat — its fields are the top-level object, with no data envelope.
• A non-paginated collection serializes as a flat JSON array.
• Only a paginated list endpoint keeps the standard data / meta / links envelope.

The paginated envelope looks like this:

{
    "data": [ /* the page of resources */ ],
    "meta": {
        "current_page": 1,
        "per_page": 25,
        "total": 240,
        "last_page": 10,
        "from": 1,
        "to": 25,
        "path": "https://clickbase.so/api/sites/example.com/goals"
    },
    "links": {
        "first": "https://clickbase.so/api/sites/example.com/goals?page=1",
        "last": "https://clickbase.so/api/sites/example.com/goals?page=10",
        "prev": null,
        "next": "https://clickbase.so/api/sites/example.com/goals?page=2"
    }
}

Paginated endpoints

These are the only endpoints that return the data / meta / links envelope. Every other data endpoint returns a flat object or flat array.

Advance through pages with ?page=. Where per_page is accepted it is validated as an integer 1–100; a value outside that range returns 422. The sessions and replays lists page at a fixed internal size, so they take ?page= but not ?per_page=.

Money

Money is always an integer in minor units (cents) — never a float and never a formatted string. A revenue of 4200 means $42.00. This holds everywhere revenue appears (goal revenue, the Revenue reports, session/user values). Format for display on your side by dividing by 100 for a two-decimal currency; the currency itself is reported separately as an ISO 4217 code.

Date ranges

Every reporting endpoint accepts the same date-range inputs. Pass either a preset range or an explicit from/to pair (which takes precedence). Boundaries are computed in the site's own timezone, then converted to UTC.

Preset range values (from App\Actions\Stats\ResolveDateRange::RANGES):

When range is missing or unrecognized it falls back to today.

Custom range — supply both from and to as Y-m-d dates (e.g. from=2026-01-01&to=2026-01-31). Both must be valid and from must be on or before to, otherwise the pair is ignored and the preset range applies.

curl "https://clickbase.so/api/sites/example.com/stats/events?range=last_7_days" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

const params = new URLSearchParams({ range: 'last_7_days' });
await fetch(`https://clickbase.so/api/sites/example.com/stats/events?${params}`, {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

import requests

requests.get(
    'https://clickbase.so/api/sites/example.com/stats/events',
    params={'range': 'last_7_days'},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Filters

Reporting endpoints accept the same dashboard filter keys as query parameters (allowlisted in App\Actions\Stats\ResolveFilters). Any key not in this list is ignored.

Each dimension takes a single value or a list. Repeat the key with [] to match any of several values (WHERE IN):

?country=BR
?path[]=/pricing&path[]=/signup

visit_count is single-value and uses an operator prefix — all-time tracked session count per visitor:

?visit_count=is:1
?visit_count=gte:2
?visit_count=lte:5

Operators: is, gte, lte. The prop_key / prop_value pair must be supplied together — either both are present (non-empty) or neither is applied.

curl "https://clickbase.so/api/sites/example.com/stats/events?country=BR&path[]=/pricing&path[]=/signup" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

const params = new URLSearchParams({ country: 'BR' });
params.append('path[]', '/pricing');
params.append('path[]', '/signup');
await fetch(`https://clickbase.so/api/sites/example.com/stats/events?${params}`, {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

import requests

requests.get(
    'https://clickbase.so/api/sites/example.com/stats/events',
    params={'country': 'BR', 'path[]': ['/pricing', '/signup']},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

Errors & status codes

A validation error (422) carries a message and an errors map keyed by field name:

{
    "message": "The range field must be a string.",
    "errors": {
        "range": ["The range field must be a string."]
    }
}

Other errors carry a plain message:

{
    "message": "An active subscription is required to access this team."
}