Stimuli

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:

1. Presign — request a short-lived S3 upload URL for each file.
2. Upload — POST the file directly to S3 using the presigned URL.
3. Confirm — register the uploaded file with Persona to create the stimuli record.
4. List — call GET /v1/stimuli to retrieve stimuli_id values for your uploaded assets.
5. 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.

Text-only stimulus questions

A stimulus doesn't have to carry media. To add a plain question with no image or video — for example a standalone question between two media stimuli — call Assign without a stimuli_id. Persona creates the stimulus record for you and returns its stimuli_id. Skip the presign, upload, and confirm steps entirely.

This is also how you edit questions on a STIMULI project — PATCH /v1/projects/{project_id} rejects questions for stimuli projects.

List stimuli

Returns all uploaded stimuli for a project, ordered by display position. Use this to retrieve stimuli_id values for the assign endpoint.

Example request

curl "https://external-api.prod.insightscompany.io/v1/stimuli?project_id=<project_id>" \
-H "x-api-key: <api_key>"

Query parameters

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": [
        { "question": "What do you notice first?", "probing_level": "low", "instructions": null },
        { "question": "How does this make you feel?", "probing_level": "medium", "instructions": null }
      ]
    }
  ],
  "total": 1
}

Presign an upload

Returns a presigned S3 POST URL and form fields for a direct upload. Call Confirm after the upload completes.

Example request

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

Example response

// request sent image/png — the API stores it as webp
{
  "upload_url": "https://s3.amazonaws.com/...",
  "upload_fields": {
    "Content-Type": "image/webp",
    "key": "stimuli/prod/<interview_id>/<file_id>.webp",
    "...": "..."
  },
  "file_id": "a1b2c3d4-...",
  "s3_key": "stimuli/prod/<interview_id>/<file_id>.webp",
  "media_url": "https://cdn.example.com/stimuli/<file_id>.webp",
  "expires_in": 3600,
  "content_type": "image/webp"
}

Uploading to S3

POST the file to upload_url as multipart/form-data. Include every entry from upload_fields as a form field first (in the order returned), then the file as the last field named file:

curl -X POST "<upload_url>" \
  -F "Content-Type=<upload_fields.Content-Type>" \
  -F "key=<upload_fields.key>" \
  -F "policy=<upload_fields.policy>" \
  -F "x-amz-algorithm=<...>" \
  -F "x-amz-credential=<...>" \
  -F "x-amz-date=<...>" \
  -F "x-amz-security-token=<...>" \
  -F "x-amz-signature=<...>" \
  -F "file=@homepage-concept.png"

The file field carries your original bytes; the object is stored under the resolved key from s3_key (e.g. .webp for a JPEG/PNG upload). 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.

Example request

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": ".webp",
  "caption": "Homepage redesign concept"
}'

Request body

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.

Called without a stimuli_id, it instead creates a new text-only stimulus question (no media) and returns its stimuli_id. Only valid on STIMULI projects.

Example request

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?",
    { "question": "How does this make you feel?", "probing_level": "high" }
  ],
  "caption": "Homepage redesign concept"
}'

Request body

Example response

question_items is always returned in object form, with probing_level resolved and instructions as null when unset:

{
  "stimuli_id": "a1b2c3d4-...",
  "question_items": [
    { "question": "What do you notice first?", "probing_level": "low", "instructions": null },
    { "question": "How does this make you feel?", "probing_level": "high", "instructions": "Probe for the emotional reaction, not the design critique." }
  ],
  "caption": "Homepage redesign concept"
}

Create a text-only question

Omit stimuli_id to add a standalone question with no media. The new stimulus is appended after existing ones and its stimuli_id is returned — use that same ID with this endpoint later to edit the question text or clear it.

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>",
  "question_items": ["Before we look at anything — what matters most to you here?"]
}'

{
  "stimuli_id": "e5f6a7b8-...",
  "question_items": [
    { "question": "Before we look at anything — what matters most to you here?", "probing_level": "low", "instructions": null }
  ],
  "caption": null
}

Errors

Notes

• Supported image formats: PNG, JPEG, GIF, WebP. Maximum 10 MB. PNG and JPEG are stored as WebP — the presign response's s3_key / content_type / media_url reflect the stored format, and file_ext on Confirm must match it. GIF and WebP are stored as-is.
• Supported video format: MP4. Maximum 100 MB.
• The project_id is the id field returned when you create a project.