Calm API, MCP, install, and console surfaces for working with AYA’s digital twin system.
Developer Platform
Reference / OpenAPI
Docs
Reference / OpenAPI
Endpoint summary, OpenAPI files, and schema download entry points.
Reference
Canonical contract files
Use the OpenAPI files in the repo as the contract source of truth for the REST API and legacy ChatGPT Actions subset.
Endpoint reference
API surface
The reference below summarizes the current Twin Engine gateway surface used for the public developer platform.
/v1/panels/resolve
Resolve an audience panel from a brief, panel ID, or explicit persona IDs.
Resolve an audience panel from a brief, panel ID, or explicit persona IDs.
Parameters
X-Request-Id
header
Optional client-generated request ID for tracing.
X-AYA-Workspace-Id
header
Required when your account belongs to multiple workspaces.
Request body
panelId
uuid
Reference a saved panel by ID.
brief
string
Natural-language audience brief — AYA selects matching personas.
selectedPersonas
string[]
Explicit persona IDs to use.
limit
integer (1–12)
Max personas to return.
strict
boolean
If true, only return exact matches.
includePersonas
boolean
Include full persona objects in response.
Example request
json
{ "brief": "UK millennials interested in personal finance", "limit": 6, "includePersonas": true}
Example response (200)
json
{ "persona_ids": ["p1", "p2", "p3", "p4", "p5", "p6"], "personas": [ { "id": "p1", "name": "Sophie", "age": 29, "location": "London" } ], "panel": { "id": "...", "name": "Auto-generated" }}
/v1/concept-tests
Run a concept test against an AI audience panel. Returns 202 with a job ID.
Run a concept test against an AI audience panel. Returns 202 with a job ID.
Parameters
Idempotency-Key
header
Deduplicate retries within 24 hours.
X-Request-Id
header
Client-generated request ID.
Request body
concept
string
The concept statement to test.
brief
string
Audience brief for panel resolution.
panelId
uuid
Use a saved panel instead of brief.
selectedPersonas
string[]
Explicit persona IDs.
limit
integer (1–12)
Max personas.
webhookId
uuid
Webhook to notify on completion.
Example request
json
{ "brief": "UK fintech app for first-time investors", "concept": "An investing app that explains every decision in plain English", "limit": 8}
Example response (202)
json
{ "job_id": "2d6c...", "status": "queued", "feedback_id": "f123...", "persona_ids": ["p1", "p2", "p3"]}
/v1/quick-pulse
A lighter concept test using up to 3 personas. Same async pattern, faster results.
A lighter concept test using up to 3 personas. Same async pattern, faster results.
Parameters
Idempotency-Key
header
Deduplicate retries.
Request body
concept
string
The concept to quick-test.
brief
string
Audience brief.
Example request
json
{ "concept": "A meal-kit service for single-person households", "brief": "Urban professionals aged 25-35"}
Example response (202)
json
{ "job_id": "8f4a...", "status": "queued"}
/v1/interviews
Start an automated 1:1 interview with the best-fit digital twin in a saved panel.
Start an automated 1:1 interview with the best-fit digital twin in a saved panel.
Parameters
Idempotency-Key
header
Deduplicate retries.
X-Request-Id
header
Client-generated request ID.
Request body
panelId
uuid
Saved panel used to select the best-fit interview participant.
brief
string
Research brief and interview context.
topic
string
Short interview topic.
objective
string
What the interview should learn.
maxQuestions
integer (1-8)
Maximum generated or supplied questions.
engine
"vertex" | "gemini"
Preferred execution engine.
Example request
json
{ "panelId": "00000000-0000-4000-8000-000000000001", "brief": "Understand why families might object to a premium zoo day pass", "topic": "Pricing objections", "maxQuestions": 5}
Example response (202)
json
{ "job_id": "2d6c...", "status": "queued", "participant": { "id": "p1", "name": "Sophie" }, "result_url": "/feedback/abc..."}
/v1/focus-groups/sessions
Start a multi-persona focus group session from a saved panel or focus group.
Start a multi-persona focus group session from a saved panel or focus group.
Parameters
Idempotency-Key
header
Deduplicate retries.
X-Request-Id
header
Client-generated request ID.
Request body
groupId
uuid
Saved focus group or panel id.
panelId
uuid
Alias for groupId when callers already use panel language.
brief
string
Research brief and discussion context.
objective
string
What the session should resolve.
questions
Question[]
Optional supplied discussion questions.
packageType
string
Session package label. Defaults to Custom Objective.
Example request
json
{ "groupId": "00000000-0000-4000-8000-000000000001", "brief": "Understand whether teams would adopt the new API-first research workflow", "objective": "Surface consensus, disagreement, objections, and next steps"}
Example response (202)
json
{ "job_id": "9bd2...", "status": "queued", "session_id": "1f4a...", "result_url": "/focus-group-session/1f4a..."}
/v1/interviews/messages
Send a message in a 1:1 interview with an AI persona. Synchronous response.
Send a message in a 1:1 interview with an AI persona. Synchronous response.
Parameters
X-Request-Id
header
Client-generated request ID.
Request body
personaId
string
The persona to interview.
interviewId
uuid
Continue an existing interview session.
mode
"reply" | "suggest" | "summarize"
Response mode. Defaults to reply.
history
Message[]
Prior conversation messages.
Example request
json
{ "personaId": "p1", "mode": "reply", "history": [ { "role": "user", "content": "What would make you switch banks?" } ]}
Example response (200)
json
{ "response": "I'd need to see lower fees and a better mobile app..."}
/v1/assets/analyze
Submit an image for creative analysis. Returns 202 with a job ID.
Submit an image for creative analysis. Returns 202 with a job ID.
Parameters
Idempotency-Key
header
Deduplicate retries.
Request body
imageBase64
string
Base64-encoded image data.
mimeType
string
e.g. image/png, image/jpeg.
brief
string
Audience brief for context.
platform
string
Target platform (instagram, facebook, etc).
concept
string
Concept description for the asset.
Example request
json
{ "imageBase64": "iVBORw0KGgo...", "mimeType": "image/png", "brief": "Health-conscious Gen Z consumers", "platform": "instagram"}
Example response (202)
json
{ "job_id": "c9b1...", "status": "queued"}
/v1/jobs/{id}
Check the status of any async job. Poll until status is "completed" or "failed".
Check the status of any async job. Poll until status is "completed" or "failed".
Parameters
id
path
The job ID returned from a 202 response.
Example response (200)
json
{ "id": "2d6c...", "operation": "concept-tests.run", "status": "completed", "linked_resource": { "type": "concept_test_job", "id": "b473..." }, "progress": { "completed_personas": 8, "total_personas": 8 }}
/v1/webhooks/test
Send a test event to a configured webhook endpoint to verify your integration.
Send a test event to a configured webhook endpoint to verify your integration.
Request body
webhookId
uuid
The webhook to test.
event
string
Event type to simulate.
Example request
json
{ "webhookId": "wh_abc123...", "event": "job.completed"}
Example response (200)
json
{ "webhook_id": "wh_abc123...", "delivery_id": "del_xyz...", "event": "job.completed", "response_code": 200, "delivered": true}
On this page