Docs · REST API

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 to build your own widget integration.

Authentication Responses Rate limits Endpoints

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

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 below. 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

CodeMeaning
200 OKRequest succeeded
201 CreatedResource created
204 No ContentRequest succeeded, no body returned
400 Bad RequestValidation error — check request body
401 UnauthorizedMissing or invalid API key
403 ForbiddenValid key but not allowed: endpoint outside the widget allowlist (API_KEY_NOT_PERMITTED), origin not on your domain allowlist, or plan limit
404 Not FoundResource does not exist
429 Too Many RequestsRate limit or AI quota exceeded
500 Internal Server ErrorUnexpected error — include traceId when contacting support

Rate limits

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

PlanAPI calls / minute
Free (no active plan)60
Solo120
Starter200
Pro500
EnterpriseCustom

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.

API endpoints

All endpoints are prefixed with https://api.incluxa.com/api/v1. This list is what your widget key (X-Api-Key: inc_live_…) can call. The <script> embed and the SDKs call these for you; you only need them to build your own widget integration.

A widget key is publishable, so any endpoint not listed here answers 403 with the code API_KEY_NOT_PERMITTED.

Widget

GET/widget/configWidget configuration for your key (checks the page origin against your domain allowlist)
GET/widget/plan-featuresTools and theme your plan enables
POST/widget/boot-tokenShort-lived widget token used by the embed
POST/widget/feedbackVisitor feedback (rating 1–5, category, optional comment)
POST/widget/reportVisitor accessibility report

Presets

GET/presetsList the available presets and their tools

Profiles

Profiles store one visitor's accessibility preferences. The userId is your system's identifier for that visitor. GET returns a short-lived profileToken; a PUT must send it back in the X-Profile-Token header, so a key alone cannot overwrite any profile.

GET/profiles/{userId}Profile with feature settings and a profileToken
GET/profiles/{userId}/active-featuresOnly the enabled features (lightweight)
PUT/profiles/{userId}Update feature settings (needs X-Profile-Token)

Get a profile

curl https://api.incluxa.com/api/v1/profiles/user_123 \
  -H "X-Api-Key: inc_live_YOUR_KEY"

Update a profile

curl -X PUT https://api.incluxa.com/api/v1/profiles/user_123 \
  -H "X-Api-Key: inc_live_YOUR_KEY" \
  -H "X-Profile-Token: PROFILE_TOKEN_FROM_GET" \
  -H "Content-Type: application/json" \
  -d '{
    "features": [
      { "featureCode": "reading_mask", "isEnabled": true },
      { "featureCode": "text_zoom", "isEnabled": true, "value": "150" }
    ]
  }'

To apply a preset, read it from GET /presets and send its tools in a profile update. Deleting a profile is done in the portal.

Usage events

POST/analytics/logRecord that a visitor turned a tool on or off

The SDK sends these automatically when trackUsage is enabled. Usage reports are read in the portal, not with the key.

AI content transforms

These use AI credits from your plan's AI add-on.

POST/content/simplifySimplify text to a target reading level
POST/content/alt-textSuggest alt text for an image
POST/content/vocabularyPick out vocabulary words from text
POST/content/hintsScaffolded hints for a question
POST/content/rephraseRephrase text
POST/content/translateTranslate text to a target language
POST/content/summarizeSummarize a passage
POST/content/aria-fixSuggest ARIA fixes for a page fragment
POST/content/tts-exportText-to-speech export

Simplify text

curl -X POST https://api.incluxa.com/api/v1/content/simplify \
  -H "X-Api-Key: inc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The mitochondria is the powerhouse of the cell.",
    "targetGradeLevel": 5
  }'

Everything else: the portal

WCAG scanning and results, compliance targets and VPAT / compliance reports, sites and the widget domain allowlist, usage analytics, team members and the audit log, widget keys, webhooks and billing are managed in the INCLUXA portal while you are signed in. There are no management API keys today.

Health

GEThttps://api.incluxa.com/healthAPI health check (outside /api/v1; no key needed)

Start building

Create a widget key in the portal, then explore the JavaScript SDK to wire INCLUXA into your product.

Get a widget key Read the SDK docs