Test creative with the API

Overview#

A creative test shows your ads, images, videos, or audio to your customers' digital twins and asks each twin to rate them. You can run the same test you run from Studio > Assets > Test existing assets from your own code, for example right after a designer exports a file from Canva or Adobe.

You need an API key with Research write access, and an audience you have set up in Point11: a business profile and its customers. Every request below sends the key as Authorization: Bearer $POINT11_API_KEY, and every request that changes something sends a new UUID in Idempotency-Key.

Upload each creative#

Upload each file in three requests. First, reserve the upload: send the file's name, type, exact size in bytes, and SHA-256 (a video sends no SHA-256):

curl https://point11.ai/api/v1/research/study-attachments/reserve-upload-v4 \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename": "summer-ad.png", "mediaType": "image/png", "byteLength": 482113, "sha256": "<hex sha-256>"}'

Then send the file as the body of the upload request in the response, with exactly its method, URL, and headers, before it expires a minute later. Finally, finish the upload with the attachment's id and the etag the upload answered:

curl https://point11.ai/api/v1/research/study-attachments/complete-upload-v3 \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"id": "<attachment id>", "etag": "<etag>"}'

Images (PNG, JPEG, WebP) can be up to 3,750,000 bytes, the most one picture can carry to every AI model a twin may run on, PDFs and audio (MP3, WAV) up to 4 MiB, and videos (MP4, WebM) up to 100 MiB and 3 minutes. Twins see a video as timed frames and its transcript, so wait until GET /api/v1/research/study-attachments-v2/{id} shows its storyboard as ready.

Start the test#

Name the uploaded files, what you want to learn, the audience, and how twins should meet the creative:

curl https://point11.ai/api/v1/research/creative-tests/start \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer ads",
    "brief": "Which ad makes people want to book a visit, and why?",
    "sellerProfileId": null,
    "contentLanguage": "en",
    "audience": {
      "audienceProfileId": "<business profile id>",
      "targetedGroupIds": null,
      "targetedCustomerIds": null,
      "targetInterviewCount": 50
    },
    "studyMode": {"kind": "first_impressions"},
    "metrics": ["stopping_power", "clarity", "appeal", "intent_to_act"],
    "platforms": ["Facebook", "Instagram"],
    "attachments": [
      {"artifactId": "<attachment id>", "filename": "summer-ad.png", "mediaType": "image/png", "byteLength": 482113}
    ]
  }'

• Audience. audienceProfileId is your business profile's id from GET /api/v1/business/profiles. Leave targetedGroupIds empty to draw from all its customers, or name up to 20 saved audiences.
• First impressions or a buying situation. first_impressions shows the creative to each twin as they are. buying_scenario with a direction first places each twin in the buying situation you describe.
• Metrics. Each metric becomes one rating question per creative on one shared scale, plus a follow-up, so a test asks creatives × (metrics + 1) questions, at most 100. With 4 metrics you can test up to 20 creatives. Platform fit needs at least one platform.

The test answers 202 at once. Keep the Idempotency-Key you sent: it names the test from now on.

Follow the test#

While Point11 reads your creative and prepares the twins, read the test by that key:

curl https://point11.ai/api/v1/research/creative-tests/$TEST_KEY \
  -H "Authorization: Bearer $POINT11_API_KEY"

status is preparing, then launched, failed, or unsupported, and phase says how far it has got. Only the key that started a test can read it this way. Once it is launched, campaignId and runId name its interviews and results.

The interviews take longer, so instead of reading every test, read your organization's activity revision every 30 to 60 seconds. It changes when any study finishes or its results publish, so one request covers all your tests:

curl https://point11.ai/api/v1/campaigns/activity-revisions/organization \
  -H "Authorization: Bearer $POINT11_API_KEY"

When products.research changes, read the results.

Read the scorecard#

curl "https://point11.ai/api/v1/research/results-v7/$CAMPAIGN_ID?runId=$RUN_ID" \
  -H "Authorization: Bearer $POINT11_API_KEY"

The results give each question's answers, a summary with quotes, how many interviews finished, and the scorecard: each metric for each creative and overall. Results are simulated research with your customers' digital twins, not measured clicks, sales, or conversion.

Costs and limits#

• A creative test is billed like any Research study: each delivered interview counts toward your plan at the Research interview price, and reading the creative and preparing the twins use Alpha credits at their exact cost.
• Each key has 100 requests a minute across the API and the MCP server. A key can start about 6 tests a minute, and upload 128 files a minute and 300 a day. When a budget runs out you get 429; wait the Retry-After seconds.
• To retry a request safely, send it again with the same Idempotency-Key. Retrying a start gives you the same test back, and nothing is charged twice.