API Reference

Complete reference for the Intentara REST API.

Base URL

https://platform.intentara.com/api/v1/public/creatives

Authentication

All requests require an API key passed via the x-api-key header:

bash

curl -H "x-api-key: pub_XXXX" https://platform.intentara.com/api/v1/public/creatives/...

Public publisher key Keys starting with pub_ are intended for public client-side integrations. They are publisher-scoped access keys, not confidential server secrets, but you should still manage them operationally and rotate or deactivate them if needed.

Endpoints

Get Ad by Context

POST /by-context

Retrieve the most relevant ad creative for a given text context. This is the recommended endpoint for all integrations.

Parameter	Type	Description
context required	string	The conversation context text, typically the previous chat history plus the current user input.

Request

{
  "context": "I need a good pair of running shoes for a marathon"
}

Response

{
  "id": "abc123",
  "name": "Marathon Pro Shoes",
  "text": "Train harder, run faster — Marathon Pro X1 now available.",
  "imageUrl": "__BASE_URL__/api/v1/public/creatives/images/shoe.jpg",
  "impressionUrl": "__BASE_URL__/api/v1/public/creatives/beacon?requestId=req_xyz",
  "targetUrl": "__BASE_URL__/api/v1/public/creatives/target/abc123?requestId=req_xyz"
}

Tracking

Every ad response includes URLs for impression and click tracking. Proper tracking is essential for reporting and billing.

Impression Tracking

The impressionUrl (beacon) must always be loaded for every ad impression, regardless of ad type. The SDK handles this automatically. For direct API integrations, load the impressionUrl as an image pixel after displaying the ad.

GET /beacon?requestId={requestId}

Returns a 1x1 transparent tracking pixel (GIF). Load this URL as an image to record an impression. Must be fired for every ad displayed.

Parameter	Type	Description
requestId required	string	The request ID from the ad response (included in impressionUrl).

When using the API directly, always load the impressionUrl as an image:

javascript

// Impression tracking — always fire the beacon
const pixel = new Image();
pixel.src = ad.impressionUrl;

Click Tracking

GET /target/{creativeId}?requestId={requestId}

Redirects to the advertiser's landing page while recording a click event. Always use the targetUrl from the ad response as the click-through link.

Parameter	Type	Description
creativeId required	string	The creative ID (path parameter).
requestId optional	string	The request ID for attribution (query parameter).

Simply use the targetUrl from the ad response as the href for clickable elements. The redirect handles click tracking automatically.

Error Responses

The API uses standard HTTP status codes:

Status	Meaning
200	Success — ad creative returned
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or expired API key
404	No matching creative found
500	Internal server error

Error responses include a JSON body:

json

{
  "error": "No creative found matching the provided criteria"
}