REST API

The INCLUXA REST API is what the widget talks to: visitor profiles, presets, usage events, feedback and AI content transforms. You only need it directly if you build your own widget integration; the <script> embed and the SDKs call it for you.

Base URL

https://api.incluxa.com/api/v1

Authentication

Widget requests carry your widget key in the request header:

X-Api-Key: inc_live_YOUR_KEY

Important

A widget key is publishable: it appears in your page source, the same way it does in the <script data-key> embed. That is why it can only reach the widget endpoints listed under Endpoints. Any other endpoint answers 403 API_KEY_NOT_PERMITTED. Keep your widget domain allowlist up to date in the portal so the widget only loads on your sites.

Scanning, compliance reports, sites, analytics, team, keys, webhooks and billing are managed in the INCLUXA portal while you are signed in. There are no management API keys today.

Widget keys are created in the INCLUXA Portal under API Keys. Each key is shown exactly once at creation — it cannot be retrieved again. If you lose a key, revoke it and create a new one.

Response format

All responses are JSON. Successful responses use HTTP 2xx status codes.

Error responses include an error message and a traceId for support:

{
  "error": "Profile not found",
  "traceId": "0HN1234567890:00000001"
}

HTTP status codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created
204 No Content	Request succeeded, no body returned
400 Bad Request	Validation error — check request body
401 Unauthorized	Missing or invalid API key
403 Forbidden	Valid key but not allowed: endpoint outside the widget allowlist (API_KEY_NOT_PERMITTED), origin not on your domain allowlist, or plan limit
404 Not Found	Resource does not exist
429 Too Many Requests	Rate limit or AI quota exceeded
500 Internal Server Error	Unexpected error — include traceId when contacting support

Rate limits

Rate limits are enforced per tenant per minute and vary by plan:

Plan	API calls / minute
Free (no active plan)	60
Solo	120
Starter	200
Pro	500
Enterprise	Custom

When you hit a rate limit, the API returns 429 Too Many Requests. Retry after the Retry-After header value (in seconds).

Versioning

The current API version is v1. Breaking changes will be introduced in new versions (v2, etc.) with a minimum 6-month deprecation notice. Non-breaking additions (new fields, new endpoints) may be added to v1 at any time.

Pagination

List endpoints accept page (default: 1) and pageSize (default: 50, max: 100) query parameters. Paginated responses include totalCount, page, pageSize, and totalPages.