Listen Labs API - Listen Labs

The Listen Labs API lets you run studies entirely from code: define a study guide as JSON, create a draft, launch it to get a self-recruit link you can distribute to participants, and pull responses back out once interviews come in.

Base URL

https://listenlabs.ai

Authentication

All endpoints authenticate with an API key passed in the x-api-key header. The key is scoped to a single organization — studies are created in, and wallets are listed for, that organization.

curl 'https://listenlabs.ai/api/public/v1/wallets' \
  -H 'x-api-key: <api_key>'

Admins and Supervisors can create API keys from the Developer section of their account page on Listen. See Get API Access for details.

Workflow

Create a draft study

POST /api/public/v1/studies/create with a title and a study guide. The guide is validated up front; if it passes, you get back a draft study’s id and linkId. Nothing is visible to participants yet — you can still review or edit the draft in the dashboard.

Pick a wallet (optional)

GET /api/public/v1/wallets lists the wallets granted to your organization with their recruitment and project credit balances. walletId can only be omitted at launch when your organization has exactly one wallet (it’s auto-selected). If you have access to more than one, omitting it returns a 400 (wallet_required) — you must pass one from this list.

Launch

POST /api/public/v1/studies/{studyId}/launch publishes the draft and opens its self-recruit link. The response includes selfRecruitLink — share it with participants (or plug it into your own recruitment flow). Project responses bill to the launch wallet.

Retrieve responses

Once interviews come in, pull them with Get Responses (GET /api/public/v1/responses/{linkId}) and drill into a single transcript with Get Single Response. The linkId comes back from create/launch, or from List Studies. The Data Map shows how these entities join together.

Quickstart

A complete create → launch example you can copy and run.

Endpoints

Endpoint	Description
`POST /api/public/v1/studies/create`	Validate a study guide and create a draft study
`POST /api/public/v1/studies/{studyId}/launch`	Publish a draft and return the self-recruit link
`GET /api/public/v1/wallets`	List the organization’s wallets with balances
`GET /api/public/v1/responses/{linkId}`	List all responses for a study
`GET /api/public/v1/responses/{linkId}/{responseId}`	Retrieve a single response
`GET /api/public/list_surveys`	List all studies in the organization
`GET /api/public/studies/{study_id}/questions`	List all questions for a study

The unversioned response endpoints — GET /api/public/responses/{link_id} and GET /api/public/responses/{link_id}/{response_id} — are deprecated starting August 1, 2026. Migrate to the versioned /api/public/v1/responses/... endpoints above before then.

Errors

Every error response from the /api/public/v1/* endpoints shares one JSON envelope:

error — a human-readable message. Useful for logs, but it may change; don’t branch on it.
code — a stable, machine-readable identifier. Branch on this.
issues — present only on 400 schema failures (code: invalid_request_body): an array of per-field violations, each with a path and message.

400 Schema violation

{
  "error": "Invalid request body",
  "code": "invalid_request_body",
  "issues": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["title"],
      "message": "Required"
    }
  ]
}

400 Invalid study guide

{
  "error": "Invalid study guide: conditional references unknown item externalId 'q2'",
  "code": "invalid_study_guide"
}

Error codes

Status	Code	Meaning
`400`	`invalid_json`	Request body isn’t valid JSON.
`400`	`invalid_request_body`	Body failed schema validation. See `issues` for per-field details.
`400`	`invalid_study_guide`	The study guide broke a cross-field rule (create only).
`400`	`wallet_required`	The organization has multiple wallets and `walletId` was omitted (launch only).
`400`	`insufficient_credits`	The wallet can’t fund the launch — insufficient balance or grant limit (launch only).
`400`	`bad_request`	A query or path parameter is invalid (response endpoints only).
`401`	`missing_api_key`	No `x-api-key` header.
`401`	`invalid_api_key`	The API key is invalid.
`403`	`forbidden`	The key’s user isn’t a member of the key’s organization.
`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.
`404`	`response_not_found`	Response not found in the study (get response only).
`409`	`concurrent_modification`	The draft was modified concurrently; retry (create only).
`409`	`study_busy`	An update is in flight; retry after a moment (launch only).
`409`	`conflict`	The publish raced a concurrent edit; refresh and retry (launch only).
`500`	`internal_error`	Internal error. Details are logged server-side, not returned.

Beyond field-level validation, the server enforces cross-field rules on the study guide (screening block placement, minSelect/maxSelect coupling, unique externalIds, reference resolution, exclusiveOption placement) and returns violations as 400 responses (code: invalid_study_guide). The full list is in the Study Guide Reference.

​Base URL

​Authentication

​Workflow

Quickstart

​Endpoints

​Errors

​Error codes

Base URL

Authentication

Workflow

Endpoints

Errors

Error codes