# Test creative with the API

Upload ads and other creative, test them against your customers' digital twins, and read the scorecard from your own code.

Source: https://point11.ai/docs/mcp/creative-testing  
Updated: 2026-10-18

## 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](/docs/mcp/overview) 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):

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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.