Reference

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/api

Authentication and API keys

Send your key in theX-API-Keyheader. There are two kinds of key, and they are not interchangeable.

KeyWhereCan call
gi_pk_… publishablePage 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_… secretYour 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

FieldTypeRequiredDescription
siteIdstringYesYour site ID (found in Dashboard > Install)
utmParamsobjectYesObject with utm_source, utm_medium, utm_campaign, utm_term, utm_content
selectorsstring[]YesCSS selectors for elements to personalize
intentstringNoDirect intent signal (takes priority over utm_term)
pageContextstringNoAdditional context about the page content
visitorIdstringNoYour 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.
sessionIdstringNoSession 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

AttributeRequiredDescription
data-api-keyYesThe site's publishable key (starts with gi_pk_). Never a secret key.
data-site-idYesYour site ID
data-debugNoSet to "true" to enable verbose console logging
data-custom-*NoCustom 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.csv

One 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

CodeMeaning
401Missing or invalid API key
403The 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
404Site or organization not found
429Rate limit exceeded (200 req/min per org). Check the Retry-After header for when to retry.
500Internal 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.