Stimuli
Upload images and videos to a STIMULI project and assign them to interview questions.
Stimuli are media assets — images or videos — shown to participants alongside specific interview questions. They are only available on projects created with type: "STIMULI".
All stimuli endpoints accept a project_id. The project_id is returned when you create a project.
To inspect uploaded assets at any time, use GET /v1/stimuli — it returns every stimuli record for a project including its ID, image/video URL, caption, display order, and current question assignments.
The upload workflow is:
- Presign — request a short-lived S3 upload URL for each file.
- Upload — POST the file directly to S3 using the presigned URL.
- Confirm — register the uploaded file with Persona to create the stimuli record.
- List — call
GET /v1/stimulito retrievestimuli_idvalues for your uploaded assets. - Assign — link each asset to the questions it should appear alongside.
All stimuli must have at least one question assigned before the project can be launched.
List stimuli
Returns all uploaded stimuli for a project, ordered by display position. Use this to retrieve stimuli_id values for the assign endpoint.
Returns all uploaded stimuli for a project, ordered by display order.
Authentication
x-api-key headerQuery Parameters
| Name | Type | Description |
|---|---|---|
project_id* | string | The project UUID. |
Headers
| Name | Type | Description |
|---|---|---|
x-api-key | string | — |
Responses
| Field | Type | Description |
|---|---|---|
itemsrequired | object[] | — |
↳ stimuli_idrequired | string | Stimuli Id |
↳ display_orderrequired | integer | Display Order |
↳ image_urlrequired | string | Image Url |
↳ video_urlrequired | string | Video Url |
↳ captionrequired | string | — |
↳ question_itemsrequired | string[] | Question Items |
totalrequired | integer | — |
Example request
GET /v1/stimuli
curl "https://external-api.prod.insightscompany.io/v1/stimuli?project_id=<project_id>" \
-H "x-api-key: <api_key>"Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id | UUID | Yes | The project UUID |
Example response
{
"items": [
{
"stimuli_id": "a1b2c3d4-...",
"display_order": 1,
"image_url": "https://cdn.example.com/stimuli/...",
"video_url": null,
"caption": "Homepage redesign concept",
"question_items": ["What do you notice first?", "How does this make you feel?"]
}
],
"total": 1
}| Field | Description |
|---|---|
stimuli_id | Use this in the Assign endpoint |
display_order | The order assets are shown to participants |
question_items | Question texts this asset is currently assigned to |
Presign an upload
Returns a presigned S3 POST URL and form fields for a direct upload. Call Confirm after the upload completes.
Returns a presigned S3 POST URL and form fields. POST a multipart/form-data request with the fields followed by the file, then call /stimuli/confirm to create the stimuli record.
Authentication
x-api-key headerHeaders
| Name | Type | Description |
|---|---|---|
x-api-key | string | — |
Request Bodyrequired
| Field | Type | Description |
|---|---|---|
project_idrequired | string | The project UUID. |
filenamerequired | string | Original filename including extension. |
content_typerequired | string | MIME type of the file. |
file_size_bytes | integer | File size in bytes, used for pre-validation. |
file_id | string | Optional pre-assigned UUID for the stimuli asset. |
Responses
| Field | Type | Description |
|---|---|---|
upload_urlrequired | string | Upload Url |
upload_fieldsrequired | object | Upload Fields |
file_idrequired | string | File Id |
s3_keyrequired | string | S3 Key |
media_urlrequired | string | Media Url |
expires_inrequired | integer | Expires In |
content_typerequired | string | Content Type |
Example request
POST /v1/stimuli/presign
curl -X POST "https://external-api.prod.insightscompany.io/v1/stimuli/presign" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
"project_id": "<project_id>",
"filename": "homepage-concept.png",
"content_type": "image/png"
}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
project_id | UUID | Yes | The project UUID |
filename | string | Yes | Original filename including extension |
content_type | string | Yes | MIME type of the file (e.g. image/png, video/mp4) |
file_size_bytes | integer | No | File size in bytes — used for pre-validation before the upload |
file_id | UUID | No | Pre-assigned UUID for the stimuli asset. A new UUID is generated if omitted |
Example response
{
"upload_url": "https://s3.amazonaws.com/...",
"upload_fields": {
"Content-Type": "image/png",
"key": "stimuli/prod/<interview_id>/<file_id>.png",
"...": "..."
},
"file_id": "a1b2c3d4-...",
"s3_key": "stimuli/prod/<interview_id>/<file_id>.png",
"media_url": "https://cdn.example.com/stimuli/...",
"expires_in": 3600,
"content_type": "image/png"
}| Field | Description |
|---|---|
upload_url | The S3 endpoint to POST the file to |
upload_fields | Form fields that must be included in the multipart upload, before the file |
file_id | Save this — required in the Confirm call |
expires_in | Seconds until the presigned URL expires |
Uploading to S3
POST the file to upload_url as multipart/form-data. Include all upload_fields first, then the file:
curl -X POST "<upload_url>" \
-F "Content-Type=image/png" \
-F "key=<s3_key>" \
-F "<...other upload_fields...>" \
-F "file=@homepage-concept.png"A successful upload returns HTTP 204 No Content. Then call Confirm.
Confirm an upload
Verifies the file exists in storage and creates the stimuli record.
Call after uploading the file to the presigned URL. Creates a Stimuli record attached to the interview.
Authentication
x-api-key headerHeaders
| Name | Type | Description |
|---|---|---|
x-api-key | string | — |
Request Bodyrequired
| Field | Type | Description |
|---|---|---|
project_idrequired | string | The project UUID. |
file_idrequired | string | The file_id returned from the presign step. |
file_extrequired | string | The file extension (e.g. .webp, .mp4). |
caption | string | Optional caption shown below the media. |
Responses
| Field | Type | Description |
|---|---|---|
messagerequired | string | — |
file_idrequired | string | File Id |
media_urlrequired | string | Media Url |
Example request
POST /v1/stimuli/confirm
curl -X POST "https://external-api.prod.insightscompany.io/v1/stimuli/confirm" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
"project_id": "<project_id>",
"file_id": "<file_id>",
"file_ext": ".png",
"caption": "Homepage redesign concept"
}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
project_id | UUID | Yes | The project UUID |
file_id | UUID | Yes | The file_id returned from the presign step |
file_ext | string | Yes | File extension including the leading dot (e.g. .png, .mp4) |
caption | string | No | Caption shown below the media. Can also be set or updated later via the Assign endpoint |
Example response
{
"message": "Upload finalized",
"file_id": "a1b2c3d4-...",
"media_url": "https://cdn.example.com/stimuli/..."
}Assign stimuli to questions
Sets which questions a stimuli asset appears alongside during the interview. Pass an empty question_items list to clear all assignments.
Sets which questions a stimuli asset appears alongside during the interview. Pass an empty list to clear all assignments. All stimuli must have at least one question assigned before the project can be launched.
Authentication
x-api-key headerHeaders
| Name | Type | Description |
|---|---|---|
x-api-key | string | — |
Request Bodyrequired
| Field | Type | Description |
|---|---|---|
project_idrequired | string | The project UUID. |
stimuli_idrequired | string | The stimuli UUID to assign. |
question_itemsrequired | string[] | Question texts this stimuli should appear alongside. Use exact strings from the interview. |
caption | string | Optional caption shown below the media. Send null to clear an existing caption. |
Responses
| Field | Type | Description |
|---|---|---|
stimuli_idrequired | string | Stimuli Id |
question_itemsrequired | string[] | Question Items |
captionrequired | string | — |
Example request
POST /v1/stimuli/assign
curl -X POST "https://external-api.prod.insightscompany.io/v1/stimuli/assign" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
"project_id": "<project_id>",
"stimuli_id": "<stimuli_id>",
"question_items": [
"What do you notice first?",
"How does this make you feel?"
],
"caption": "Homepage redesign concept"
}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
project_id | UUID | Yes | The project UUID |
stimuli_id | UUID | Yes | The stimuli UUID — from the confirm response or the list endpoint |
question_items | string[] | Yes | Exact question texts this asset should appear alongside. Pass an empty array to clear all assignments |
caption | string | No | Caption shown below the media. Omit to leave the existing caption unchanged |
Example response
{
"stimuli_id": "a1b2c3d4-...",
"question_items": ["What do you notice first?", "How does this make you feel?"],
"caption": "Homepage redesign concept"
}Notes
- Supported image formats: PNG, JPEG, GIF, WebP, HEIC, HEIF, AVIF, SVG. Maximum 10 MB.
- Supported video formats: MP4, MOV, WebM, AVI, MKV. Maximum 100 MB.
- The
project_idis theidfield returned when you create a project.