API Reference
Use the GetIntent REST API to personalize content programmatically. All requests require an API key: a publishable key in the browser, a secret key on your server.
Base URL
https://getintent.co/apiAuthentication and API keys
Send your key in theX-API-Keyheader. There are two kinds of key, and they are not interchangeable.
| Key | Where | Can call |
|---|---|---|
| gi_pk_… publishable | Page source: pixel, browser SDK. Bound to one site. | Public endpoints only: POST /api/rewrite,GET /api/rewrite/check, GET /api/pixel/config,POST /api/analytics, POST /api/v1/personalize,POST /api/v1/conversions, GET /api/sites/{id}/page-config. In a browser, the request must come from the site's domain (or a subdomain, or localhost). |
| gi_sk_… secret | Your server only. One site or all sites. | The public endpoints, plus the admin endpoints its scopes allow:experiments:read, experiments:write,experiments:export, sources:read,sources:write, insights:read,insights:write, usage:read. A request with a browser Origin header is refused. |
curl "https://getintent.co/api/experiments?siteId=YOUR_SITE_ID" \
-H "X-API-Key: $GETINTENT_SECRET_KEY"Create, rotate and revoke keys inDashboard > Settings > API Keys. A key is shown once and stored only as a hash. Rotating a key issues a new one and keeps the old one working for 24 hours. A key bound to a site cannot read or change anything on another site (404).
Older gi_ keys
Keys created before 28 October 2026 start with gi_ (no pk_ orsk_). They keep working for the public endpoints with no end date, so installed pixels need no change. Until 5 January 2027 they can also call the admin endpoints; those responses carry Deprecation,Sunset and X-GetIntent-Warning headers. After that date an admin call with an older key returns 403legacy_key_admin_access_ended. Switch server integrations to a secret key.
Rate Limits
The API is rate-limited to 200 requests per minute per organization. If you exceed the limit, you'll receive a 429 response with a Retry-After header indicating when you can retry.
POST/v1/personalize
Generate personalized content for a page based on visitor intent signals. This is the same endpoint the pixel script calls internally.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| siteId | string | Yes | Your site ID (found in Dashboard > Install) |
| utmParams | object | Yes | Object with utm_source, utm_medium, utm_campaign, utm_term, utm_content |
| selectors | string[] | Yes | CSS selectors for elements to personalize |
| intent | string | No | Direct intent signal (takes priority over utm_term) |
| pageContext | string | No | Additional context about the page content |
| visitorId | string | No | Your stable identifier for the visitor. A/B test assignment is sticky per visitorId (without it, GetIntent hashes the IP address and user agent of the request). Send the same value with conversions to POST /api/v1/conversions. |
| sessionId | string | No | Session identifier for grouping page views |
Example Request
curl -X POST https://getintent.co/api/v1/personalize \
-H "Content-Type: application/json" \
-H "X-API-Key: gi_pk_your_publishable_key" \
-d '{
"siteId": "YOUR_SITE_ID",
"utmParams": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "brand",
"utm_term": "crm for startups"
},
"selectors": ["h1", ".hero-subtitle", ".cta-button"],
"intent": "crm for startups"
}'Response
Returns personalized content mapped to each selector, along with metadata about the personalization.
{
"success": true,
"transformations": {
"h1": "The CRM Built for Startups",
".hero-subtitle": "Start closing more deals from day one",
".cta-button": "Try Free for 14 Days"
},
"metadata": {
"intentScore": 0.85,
"intentLevel": "high",
"cacheHit": false,
"variant": "personalized",
"experiment": {
"experimentId": "clx0exp...",
"variantId": "clx0var...",
"variantName": "Control",
"arm": "personalized"
}
}
}When the visitor is in a running A/B test, metadata.experiment names the arm. In the holdout, arm is "holdout", variant is "control" and transformations is empty: render your original content. Outside an experiment experiment is null.
Pixel Script
For most use cases, the pixel script handles everything automatically. Embed it on your page and it will call the personalization API, replace content, and track conversions without any custom code.
<script
src="https://getintent.co/api/pixel"
data-api-key="gi_pk_your_publishable_key"
data-site-id="YOUR_SITE_ID"
async
></script>Script Attributes
| Attribute | Required | Description |
|---|---|---|
| data-api-key | Yes | The site's publishable key (starts with gi_pk_). Never a secret key. |
| data-site-id | Yes | Your site ID |
| data-debug | No | Set to "true" to enable verbose console logging |
| data-custom-* | No | Custom parameters passed to the personalization engine (e.g. data-custom-industry="saas") |
JavaScript API
The pixel script exposes global functions and configuration for advanced use cases.
Track Conversion
// Basic conversion
window.getintentTrackConversion({})
// Named conversion with value
window.getintentTrackConversion({
name: 'purchase',
value: 149.99
})
// Count it for a specific conversion goal
window.getintentTrackConversion({
goalId: 'clx0goal...'
})
// Custom metadata
window.getintentTrackConversion({
name: 'signup',
metadata: { plan: 'free', source: 'pricing-page' }
})The function accepts a single object. GetIntent stores name, value, goalId and the metadata object. A name that matches a custom-event goal counts for that goal in A/B test results.
Server-side conversions: POST /api/v1/conversions
curl -X POST https://getintent.co/api/v1/conversions \
-H "Content-Type: application/json" \
-H "X-API-Key: $GETINTENT_SECRET_KEY" \
-d '{
"siteId": "YOUR_SITE_ID",
"visitorId": "the visitorId you sent to /api/v1/personalize",
"variantId": "metadata.experiment.variantId from that response",
"name": "demo_request",
"value": 50
}'Required: siteId (a site of the API key's organization, or the key's own site for a site key) and visitorId. Optional: variantId, goalId, name, value (0 or more), pageUrl, the UTM fields (utmSource … utmContent) and a metadata object of up to 4 KB. The response is { success, apiVersion, recorded, deduped, attributed, goalId, experimentId }. Click and page-view goals count once per visitor, so a repeat returns deduped: true. Every response carries the X-GetIntent-Api-Version header (currently 2026-10-28). The rate limit is 600 requests per minute per organization, and 120 per minute per IP address for publishable keys. Call it from your server with a secret key; a publishable key works too.
Experiment results as CSV: GET /api/experiments/{id}/export
curl https://getintent.co/api/experiments/EXPERIMENT_ID/export \
-H "X-API-Key: $GETINTENT_SECRET_KEY" -o results.csvOne row per UTC day, arm, variant and goal. The columns are described in A/B Testing. The experiment must belong to the key's organization (and site, for a site key). Needs a secret key with the experiments:export scope.
Custom Parameters via JavaScript
// Set before the pixel script loads
window.getintentConfig = {
customParams: {
industry: "saas",
plan: "enterprise"
}
};Error Codes
| Code | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 403 | The key may not call this endpoint. The code field says why: publishable_key_not_allowed, insufficient_scope, secret_key_in_browser, origin_not_allowed or legacy_key_admin_access_ended |
| 404 | Site or organization not found |
| 429 | Rate limit exceeded (200 req/min per org). Check the Retry-After header for when to retry. |
| 500 | Internal server error |
CORS
All API endpoints include permissive CORS headers (Access-Control-Allow-Origin: *) so you can call them from any domain. The pixel script handles CORS automatically.
SDKs and client libraries
GetIntent has no npm package or server-side SDK. Integrate with the script tag described in Installation or call the REST endpoints above from any language that can send an HTTPS request.
A small browser SDK (https://cdn.getintent.co/sdk/getintent.js, version 1.2.0) wraps the same endpoints: GetIntent.init({ siteId, apiKey }) calls /api/v1/personalize, and GetIntent.trackConversion({ goalId, name, value }) sends to /api/v1/conversions with the SDK's visitor ID and the experiment arm it was served, the holdout included.
Webhooks
Organization owners and admins register HTTPS endpoints under Settings > Webhooks. GetIntent sends a signed JSON POST for these events: rewrite.generated, experiment.started, experiment.winner_declared, experiment.completed, conversion, visitor.converted, site.created and site.updated.
The GetIntent-Signature header has the form t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">. Failed deliveries are retried up to eight times over about two days, and every delivery is listed in a delivery log. Payloads, verification code and the retry schedule are in the webhooks guide.
Data retention
Personalization, pageview and analytics records created through the API are kept for as long as the organization's account exists; there is no automatic expiry yet. Visitor profiles can be purged by inactivity (30 to 365 days) or all at once from Dashboard > Intent Context. See Security for the full retention policy.