> ## Documentation Index
> Fetch the complete documentation index at: https://docs.listenlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Endpoint
These endpoints all authenticate with the `x-api-key` header (see [Get API Access](/request-api)). The create, launch, and wallet endpoints below build and launch studies; the response and study endpoints further down retrieve data from studies that are already live. For the full study-guide schema (every block type, question type, conditional, and validation rule) see the [Study Creation API reference](/api-v2/overview).
# Create Study
Validates a study guide and creates a **draft** study in the API key's organization. Nothing is visible to participants until you launch it.
`POST https://listenlabs.ai/api/public/v1/studies/create`
### Request Body
`title string required`
Internal title of the study.
`externalTitle string`
Title shown to participants.
`background string`
Context about your company or product that the interviewer can draw on.
`studyGoal string`
What you are trying to learn. Guides the interviewer's follow-ups.
`config object`
Interview settings. `interviewMode` (`text`, `audio`, `audio_text`, `audio_screen`, `video`, `video_screen`), `questionLanguage` (e.g. `en`, `de`), optional `availableLanguages` for auto-translation, and optional `targetPlatforms`.
`welcomeMessage object`
Optional `title` and `message` shown before the interview starts.
`closingMessage string`
Message shown when the interview ends.
`studyGuide Block[] required`
The ordered list of blocks that make up the interview. Each block has a `type` (`flat`, `concept`, or `screening`), a `title`, and an `items` array of questions. See the [Study Guide Reference](/api-v2/study-guide) for the complete schema, all question types, conditionals, carry-forward, and cross-field validation rules.
### Response
`id uuid`
Permanent unique identifier for the study. Use it to launch.
`linkId string`
The link ID of the study (editable later in study settings). Use it with the response endpoints.
`status string`
Always `draft` for a freshly created study.
### Example Request
```bash theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/create' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{
"title": "Coffee habits — API demo",
"externalTitle": "A short interview about your coffee routine",
"background": "We are a specialty coffee brand exploring how people choose what to buy.",
"studyGoal": "Understand what drives brand switching among regular coffee drinkers.",
"config": {
"interviewMode": "audio_text",
"questionLanguage": "en"
},
"welcomeMessage": {
"title": "Thanks for joining!",
"message": "This interview takes about 10 minutes. There are no wrong answers."
},
"closingMessage": "That is all — thank you for your time!",
"studyGuide": [
{
"type": "screening",
"title": "Screener",
"items": [
{
"type": "multiple_choice",
"text": "How often do you drink coffee?",
"options": [
{ "text": "Every day", "status": "approve" },
{ "text": "A few times a week", "status": "approve" },
{ "text": "Rarely or never", "status": "reject" }
]
}
]
},
{
"type": "flat",
"title": "Interview",
"items": [
{
"externalId": "purchase-channels",
"type": "multiple_choice",
"text": "Where do you usually buy coffee?",
"multiSelect": true,
"options": [
{ "externalId": "opt-cafe", "text": "Cafés" },
{ "externalId": "opt-grocery", "text": "Grocery stores" },
{ "externalId": "opt-online", "text": "Online" },
{ "text": "Somewhere else", "exclusiveOption": true }
]
},
{
"type": "open_ended",
"text": "What do you like about buying coffee online?",
"followUp": "medium",
"conditional": {
"operator": "and",
"criteria": [
{
"type": "selectedTemplateOptions",
"questionId": "purchase-channels",
"matchingCriteria": "mustSelect",
"choices": ["opt-online"]
}
]
}
},
{
"type": "open_ended",
"text": "Tell me about the last time you tried a new coffee brand.",
"followUp": "heavy"
}
]
}
]
}'
```
### Example Response
```json theme={null}
{
"id": "9b2f1c3e-0000-0000-0000-000000000000",
"linkId": "coffee-habits-api-demo",
"status": "draft"
}
```
### Errors
Every error response returns an `error` message and a stable `code` you should branch on. `400` schema failures (`code: invalid_request_body`) also include an `issues` array pointing at the offending fields; broken study-guide rules return `code: invalid_study_guide`.
```json theme={null}
{
"error": "Invalid request body",
"code": "invalid_request_body",
"issues": [
{ "path": ["title"], "message": "Required" }
]
}
```
***
# Launch Study
Publishes a draft and returns its self-recruit link. Requires the API key's user to have permission to start recruitment on the study. Project responses bill to the launch wallet.
`POST https://listenlabs.ai/api/public/v1/studies/{studyId}/launch`
### Path Parameters
`studyId uuid`
The study's permanent `id` returned from Create Study.
### Request Body
The body is optional.
`walletId uuid`
Wallet to bill this study from; must be granted to the API key's organization (see List Wallets). It can only be omitted when the organization has exactly one wallet, which is then auto-selected. If you have access to more than one wallet, omitting it returns a `400` (`code: wallet_required`).
### Response
`id uuid`
The study's permanent identifier.
`linkId string`
The link ID of the study.
`selfRecruitLink string`
The public link to share with participants.
`status string`
Always `live` after a successful launch.
`wallet object`
The wallet this launch is billed to. Omitted when no wallet is bound (organization without wallet billing).
### Example Request
```bash theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/launch' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{ "walletId": "5e8a7d40-0000-0000-0000-000000000000" }'
```
### Example Response
```json theme={null}
{
"id": "9b2f1c3e-0000-0000-0000-000000000000",
"linkId": "coffee-habits-api-demo",
"selfRecruitLink": "https://listenlabs.ai/s/coffee-habits-api-demo",
"status": "live",
"wallet": {
"walletId": "5e8a7d40-0000-0000-0000-000000000000",
"name": "Research team",
"recruitmentCreditBalance": { "balance": 480, "usage": 20 },
"projectCreditBalance": { "balance": 950, "usage": 50 }
}
}
```
### Errors
| Status | Code | Meaning |
| ------ | -------------------------- | -------------------------------------------------------------------------------------- |
| `400` | `wallet_required` | The organization has multiple wallets and `walletId` was omitted. |
| `400` | `insufficient_credits` | The wallet can't fund the launch (insufficient balance or grant limit). |
| `403` | `launch_permission_denied` | The key's user lacks permission to launch this study. |
| `403` | `wallet_access_denied` | No access to the specified wallet. |
| `404` | `study_not_found` | Study not found in the key's organization. |
| `409` | `study_busy` / `conflict` | The study is mid-update or the publish raced a concurrent edit — retry after a moment. |
***
# List Wallets
Lists the wallets granted to the API key's organization, each with recruitment and project credit balances. Use a wallet's `walletId` when launching a study.
`GET https://listenlabs.ai/api/public/v1/wallets`
### Response
`wallets Wallet[]`
Each wallet is an object with the following fields:
* `walletId uuid` — Identifier to pass when launching a study.
* `name string` — Human-readable wallet name.
* `recruitmentCreditBalance object` — Credits for recruiting participants. Has `balance` and `usage` (includes active holds).
* `projectCreditBalance object` — Credits for project responses. Same `balance` / `usage` shape.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/v1/wallets' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
{
"wallets": [
{
"walletId": "5e8a7d40-0000-0000-0000-000000000000",
"name": "Research team",
"recruitmentCreditBalance": { "balance": 480, "usage": 20 },
"projectCreditBalance": { "balance": 950, "usage": 50 }
}
]
}
```
***
# Get Responses
**Deprecated starting August 1, 2026.** This unversioned endpoint has been replaced by
[`GET /api/public/v1/responses/{linkId}`](/api-v2/list-responses), which returns the same
data with camelCase parameters and fields. Migrate before August 1, 2026.
This endpoint lists all responses for a given study.
`GET https://listenlabs.ai/api/public/responses/{link_id}`
### Path Parameters
`link_id string`
The link ID of the study. You can find this in the study URL or via the List Studies endpoint. For example, in `https://listenlabs.ai/s/abc123` the link ID is `abc123`.
### Query Parameters
`page integer default:"0"`
The page number for pagination.
`per_page integer default:"1000"`
Number of responses to return per page.
`updated_since string`
ISO 8601 date string to filter responses updated after this date (e.g., `2023-08-18T11:51:54.649916Z`).
`include_in_progress boolean default:"true"`
Whether to include responses whose analysis is still in progress.
### Response
Returns a list of responses for the given study. Each response is an object with the following fields:
`id uuid`
Unique identifier for the response.
`response_number number`
The ordered number of the response.
`created_at string`
UTC timestamp of when the response was created.
`updated_at string`
UTC timestamp of when the response was last updated (uses the analysis completion time when available).
`progress string`
The completion progress of the response (e.g. `"complete"`, `"in_progress"`).
`response_duration_seconds number`
The total duration of the response in seconds.
`answers object`
Answers to all questions of the study.
* `Summary string` — A summary of the entire conversation. Available for all studies.
* `Question 1 string` — Everything the user said in response to question 1.
* `Question 2 string` — Everything the user said in response to question 2.
`answers_array Answer[]`
Answers to all questions of the study as an array.
* `answer_id string` — The answer ID. Matches the `answer_id` on transcript rows from the single response endpoint, enabling cross-referencing.
* `discussion_guide_question_id string` — The discussion guide question ID. Matches the `id` field from the Get Study Questions endpoint, enabling you to join answers with their question definitions.
* `concept_id string | null` — The concept ID. Null if not concept-specific.
* `question_id string deprecated` — Deprecated. Use `answer_id` instead.
* `question string` — The question text, prefixed with its number when available (e.g. `"Q1: What is your age?"`).
* `answer string` — The answer to the question.
`attributes object`
URL parameters that were passed to the study.
* `id string` — An id that is passed to the study, e.g. `https://listenlabs.ai/s/abc123?id=123`.
`short_transcript string | null`
A transcript of the entire conversation where the assistant messages are shortened to a couple of words. Can be `null` if the transcript has not been generated yet.
`short_assistant_messages string[]`
Condensed assistant turns used to build compact transcript context.
`bullet_summary string[]`
Concise bullet-point summary of the response.
`quality_score number`
Numeric response quality score, typically on a 1-5 scale.
`tags string[]`
Extracted keyword labels for the response.
`tagline string`
Short one-line synthesis for the response.
`summary string`
A natural-language summary of the response. May be omitted from the payload when a summary has not yet been generated for the response.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/responses/study123?page=0&per_page=100&updated_since=2023-08-18T00:00:00Z' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
[
{
"id": "12345678-0000-0000-0000-000000000000",
"response_number": 1,
"created_at": "2023-08-18T11:51:54.649916+00:00",
"updated_at": "2023-08-18T12:05:30.123456+00:00",
"progress": "complete",
"response_duration_seconds": 245,
"answers": {
"Summary": "Summary of response 1",
"Question 1": "Answer of question 1",
"Question 2": "Answer of question 2"
},
"answers_array": [
{
"answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
"concept_id": null,
"question_id": "f1e2d3c4-0000-0000-0000-000000000001",
"question": "Question 1",
"answer": "Answer of question 1"
},
{
"answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
"concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
"question_id": "f1e2d3c4-0000-0000-0000-000000000002",
"question": "Question 2",
"answer": "Answer of question 2"
}
],
"attributes": {
"id": "123"
},
"short_transcript": "• Welcome → Start\n• Ask for name → John\n• Thank you, bye →",
"short_assistant_messages": ["Welcome and intro", "Asked for name", "Thanked and closed"],
"bullet_summary": ["Bullet summary of response 1"],
"quality_score": 5,
"tags": ["tag-1", "tag-2"],
"tagline": "Tagline of response 1",
"summary": "Summary of response 1"
},
{
"id": "23456789-0000-0000-0000-000000000000",
"response_number": 2,
"created_at": "2023-08-19T11:51:54.649916+00:00",
"updated_at": "2023-08-19T12:10:15.789012+00:00",
"progress": "complete",
"response_duration_seconds": 312,
"answers": {
"Summary": "Summary of response 2",
"Question 1": "Answer of question 1",
"Question 2": "Answer of question 2"
},
"answers_array": [
{
"answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
"concept_id": null,
"question_id": "f1e2d3c4-0000-0000-0000-000000000001",
"question": "Question 1",
"answer": "Answer of question 1"
},
{
"answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
"concept_id": null,
"question_id": "f1e2d3c4-0000-0000-0000-000000000002",
"question": "Question 2",
"answer": "Answer of question 2"
}
],
"attributes": {
"id": "567"
},
"short_transcript": "• Welcome → Start\n• Ask for name → Alice\n• Thank you, bye →",
"short_assistant_messages": ["Welcome and intro", "Asked for name", "Thanked and closed"],
"bullet_summary": ["Bullet summary of response 2"],
"quality_score": 4,
"tags": ["tag-1", "tag-3"],
"tagline": "Tagline of response 2",
"summary": "Summary of response 2"
}
]
```
***
# Get Single Response
**Deprecated starting August 1, 2026.** This unversioned endpoint has been replaced by
[`GET /api/public/v1/responses/{linkId}/{responseId}`](/api-v2/get-response), which returns
the same data with camelCase fields and also accepts a readable numeric ID. Migrate before
August 1, 2026.
This endpoint retrieves a single response for a specific study.
`GET https://listenlabs.ai/api/public/responses/{link_id}/{response_id}`
### Path Parameters
`link_id string`
The link ID of the study. You can find this in the study URL or via the List Studies endpoint. For example, in `https://listenlabs.ai/s/abc123` the link ID is `abc123`.
`response_id string`
The unique ID of the specific response you want to retrieve.
### Response
Returns a single response with detailed information:
`id string`
Unique identifier for the response.
`survey string`
The link ID of the survey this response belongs to.
`transcript array`
A complete transcript of the conversation, with each entry containing:
* `moderator string` — The message from the assistant/moderator.
* `user string` — The response from the user.
* `discussion_guide_question_id string` — The discussion guide question ID for this row. Matches the `id` field from the Get Study Questions endpoint, enabling you to join transcript rows with their question definitions.
* `concept_id string | null` — The concept ID for this row. Null if the question isn't concept-specific.
* `answer_id string | null` — The answer ID for this question. Matches the `answer_id` in the list endpoint's `answers_array`, enabling cross-referencing between endpoints. Null for non-question rows (e.g. intro messages).
* `response_index number` — The zero-based index of this row in the conversation history.
* `is_followup boolean` — Whether this row is a follow-up to the same question as the previous row.
* `audio string | null` — A signed URL to the audio recording of the user's response, if available. This URL is valid for 1 hour. Null if no audio recording exists.
* `video object | null` — Video playback information, if available. If no video recording exists, this will be null.
* `stream_url string` — HLS stream URL for the video recording.
* `mp4_url string` — Direct MP4 download URL for the video recording.
* `question_uuid string deprecated` — Deprecated. Use `discussion_guide_question_id` instead.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/responses/study-1/12345678-0000-0000-0000-000000000000' \
-H 'x-api-key: '
```
### Example Response — Audio and Text
```json theme={null}
{
"id": "12345678-0000-0000-0000-000000000000",
"survey": "audio-survey",
"transcript": [
{
"moderator": "Welcome to our audio survey. Can you describe your experience with our product?",
"user": "The product has been very helpful for our team's workflow.",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
"concept_id": null,
"answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
"response_index": 0,
"is_followup": false,
"audio": "https://storage.listenlabs.ai/audio/responses/abc123.mp3?token=...",
"video": null,
"question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
},
{
"moderator": "What specific features do you find most useful?",
"user": "The task management and integration capabilities are standouts for us.",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
"concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
"answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
"response_index": 1,
"is_followup": false,
"audio": "https://storage.listenlabs.ai/audio/responses/def456.mp3?token=...",
"video": null,
"question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
}
]
}
```
### Example Response — Video and Text
```json theme={null}
{
"id": "23456789-0000-0000-0000-000000000000",
"survey": "video-interview",
"transcript": [
{
"moderator": "Tell us about your background in the industry.",
"user": "I've been working in software development for over 10 years, primarily focusing on frontend technologies.",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
"concept_id": null,
"answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
"response_index": 0,
"is_followup": false,
"audio": null,
"video": {
"stream_url": "https://stream.mux.com/vWx123.m3u8",
"mp4_url": "https://stream.mux.com/vWx123/capped-1080p.mp4"
},
"question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
},
{
"moderator": "What attracted you to our company?",
"user": "Your focus on innovative solutions and strong company culture really resonated with me.",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
"concept_id": null,
"answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
"response_index": 1,
"is_followup": false,
"audio": null,
"video": {
"stream_url": "https://stream.mux.com/yZ456.m3u8",
"mp4_url": "https://stream.mux.com/yZ456/capped-1080p.mp4"
},
"question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
}
]
}
```
### Example Response — Text Only
```json theme={null}
{
"id": "34567890-0000-0000-0000-000000000000",
"survey": "text-feedback",
"transcript": [
{
"moderator": "How would you rate your satisfaction with our customer service?",
"user": "I would rate it 9/10. Your support team was quick to respond and very helpful.",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
"concept_id": null,
"answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
"response_index": 0,
"is_followup": false,
"audio": null,
"video": null,
"question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
},
{
"moderator": "What suggestions do you have for improvement?",
"user": "It would be nice to have weekend support hours for urgent issues.",
"discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
"concept_id": null,
"answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
"response_index": 1,
"is_followup": false,
"audio": null,
"video": null,
"question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
}
]
}
```
***
# Get Study Questions
This endpoint retrieves all questions for a specific study.
`GET https://listenlabs.ai/api/public/studies/{study_id}/questions`
### Path Parameters
`study_id string`
The link ID of the study you want to retrieve questions for. You can find this in the study URL or via the List Studies endpoint.
### Response
Returns an object containing a list of questions from the study's latest revision. Each question includes its type and relevant metadata.
`questions array`
An array of question objects. Each question has a `type` field that determines its shape. All question types share these base fields:
* `id string` — Unique identifier for the question. Matches the `discussion_guide_question_id` field in the response endpoints, enabling you to join questions with their corresponding transcript rows and answers.
* `text string` — The question text shown to participants.
* `is_screener boolean` — Whether this question is part of the screening section.
* `type string` — The question type. One of: `open_ended`, `multiple_choice`, `ranking`, `statement`.
* `question_number number` — The human-readable question number for display purposes.
* `concepts array` — An array of concept objects attached to this question (empty if the question is not part of a concept test block). Each concept contains:
* `id string` — Unique identifier for the concept.
* `title string` — The concept title.
* `description string` — The concept description.
* `media array` — An array of media attachments, each with a `type` (`image` or `video`), a `name`, and a `url`.
* `embed_url string | null` — An optional embed URL for the concept (e.g. a Figma or prototype link).
Multiple choice questions (including scale questions) additionally include:
* `is_multi_select boolean` — Whether the participant can select multiple options.
* `options string[]` — The list of answer options.
Ranking questions additionally include:
* `options string[]` — The list of items to rank.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/studies/my-study/questions' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
{
"questions": [
{
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"text": "What is your age range?",
"is_screener": true,
"question_number": 1,
"type": "multiple_choice",
"is_multi_select": false,
"options": ["18-24", "25-34", "35-44", "45-54", "55+"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000002",
"text": "Tell us about your experience with our product.",
"is_screener": false,
"question_number": 2,
"type": "open_ended",
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000003",
"text": "Rank the following features by importance.",
"is_screener": false,
"question_number": 3,
"type": "ranking",
"options": ["Ease of use", "Performance", "Price", "Customer support"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000004",
"text": "Thank you for your feedback. We will now ask about your preferences.",
"is_screener": false,
"question_number": 4,
"type": "statement",
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000005",
"text": "Which categories interest you? Select all that apply.",
"is_screener": false,
"question_number": 5,
"type": "multiple_choice",
"is_multi_select": true,
"options": ["Technology", "Health", "Finance", "Education", "Entertainment"],
"concepts": []
}
]
}
```
***
# List Studies
This endpoint lists all studies.
`GET https://listenlabs.ai/api/public/list_surveys`
### Response
Returns a list of studies. Each study is an object with the following fields:
`id uuid`
Permanent unique identifier for the study.
`link_id string`
The link ID of the study. This is editable in the study settings so it might change.
`title string`
The title of the study.
`created_at string`
UTC timestamp of when the study was created.
`desc string`
A description of the study. E.g. "My study (10 Responses)".
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/list_surveys' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
[
{
"id": "12345678-0000-0000-0000-000000000000",
"link_id": "study-1",
"title": "Example study",
"created_at": "2023-09-02T07:07:17.960725+00:00",
"desc": "Example study (12 Responses)"
},
{
"id": "23456789-0000-0000-0000-000000000000",
"link_id": "study-2",
"title": "Example study 2",
"created_at": "2023-09-01T07:07:17.960725+00:00",
"desc": "Example study 2 (9 Responses)"
}
]
```