Overview

Envelope, headers, caching, dates, and error semantics for the AIclicks API.

The AIclicks API is read-only and JSON over HTTPS. All endpoints are GET, mounted under /api/v1/, and share the conventions below.

Base URL

https://api.aiclicks.io

All paths in the reference are appended to this base.

Authentication

Every request must include an API key as a Bearer token:

Authorization: Bearer ak_live_<your-key>

Mint keys in the dashboard under Settings → Developers. Each key inherits:

The team it was created on. Data is scoped to that team's domains.
The allowed_domains allowlist of the user who created it.
The team's developer_access flag — keys on disabled teams return 403.

Validate a key at any time with GET /validate.

Response envelope

Every successful response shares the same envelope:

{
  "data": { /* endpoint payload */ },
  "generated_at": "2026-06-17T10:00:11.218Z"
  // plus echoed query params (e.g. "domain_id", "days") for traceability
}

Field	Type	Description
`data`	object	Endpoint-specific payload. List endpoints nest under `data.items`.
`generated_at`	string	ISO-8601 timestamp when the server produced (or cached) this response.
`<echoed params>`	varies	Each endpoint echoes the meaningful query params it received.

List endpoints (/domains, /prompts, /fanout-queries) use this shape under data:

{
  "data": {
    "items": [ /* ... */ ],
    "total": 87,
    "page": 2,
    "size": 25,
    "total_pages": 4
  },
  "generated_at": "..."
}

Time-series endpoints return a flat items array under data with no pagination — one row per day in the requested window.

Response headers

Header	Purpose
`X-Cache`	`HIT`, `MISS`, or `BYPASS`. See Caching.
`X-Request-Id`	Unique id for this request. Echoes the value you sent if you set one. Include this in support tickets.
`X-RateLimit-Limit`	Max requests per minute for this key.
`X-RateLimit-Remaining`	Requests remaining in the current minute.
`X-RateLimit-Reset`	Unix epoch seconds when the rate-limit window resets.
`Retry-After`	Only on `429`. Seconds to wait before retrying.

Pagination

The list endpoints accept:

Param	Type	Default	Max	Notes
`page`	integer	`1`	—	1-indexed page number.
`size`	integer	`25`	`100`	Items per page.

Iterate until page > total_pages. No cursor-based pagination today.

Time-series endpoints do not paginate — they return all days in the requested window.

Date filtering

Time-series endpoints accept a days=N query parameter:

Range: 1–365. Default: 30.
Snapped to the nearest known bucket: 1, 7, 14, 30, 90, 180, 270, 365.
The window is [today − N days, today] in UTC.

Caching

Most endpoints are cached server-side for 1 hour per (endpoint, domain, query params). The X-Cache header tells you which path served the response:

MISS — fresh computation. Cached for the next caller.
HIT — served from cache. generated_at reflects when the cached entry was produced.
BYPASS — endpoint is not cached (e.g. /validate).

A HIT's generated_at may be up to one hour old. There is no cache-bust mechanism — invalidation is TTL-based.

Errors

All errors return JSON with a detail field:

{ "detail": "Domain not found" }

Status	Meaning
`400`	Malformed request — wrong query parameter type, value out of range, missing `domain_id`.
`401`	Missing, malformed, or revoked API key.
`403`	Valid key but no permission — wrong team, domain not in scope, `developer_access` disabled.
`404`	Domain or resource id not found, or path doesn't exist.
`405`	Wrong HTTP method on a valid path.
`429`	Rate limit exceeded. See Rate Limits.
`500`	Internal server error. Include the response `X-Request-Id` when reporting.
`502` / `503` / `504`	Upstream issue. Safe to retry with exponential backoff.

Idempotency

All endpoints are GET and therefore idempotent. Retries are always safe.

Tracing & support

To correlate requests with our logs, send your own X-Request-Id header:

curl https://api.aiclicks.io/api/v1/domains \
  -H "Authorization: Bearer $AICLICKS_API_KEY" \
  -H "X-Request-Id: $(uuidgen)"

When contacting support@aiclicks.io, include:

The full request URL.
The X-Request-Id from the response (or the one you sent).
The time of the request, with timezone.

All endpoints are mounted under /api/v1/. The contract is additive — we may add fields without warning, but won't remove or rename fields without a deprecation window. When /api/v2/ ships, /api/v1/ will run in parallel for at least 6 months. Sunset dates will be announced by email and via Deprecation / Sunset response headers (RFC 8594).

Was this page helpful?