One-line state: a real, feature-rich research platform whose docs are undermined by a starter-template OpenAPI spec, an auth rule that contradicts its own endpoints, a study_id-vs-link_id parameter mismatch, several confirmed-dead internal links, curl examples that ship an empty API key, and a language-support number that changes on almost every page.
1. Published OpenAPI spec is the unmodified Mintlify "Plant Store" template (critical)
Location: /api-reference/openapi.json (linked from /llms.txt under "OpenAPI Specs")
Problem: The only machine-readable API spec on the site is the Mintlify starter example: "title": "OpenAPI Plant Store", "servers": [{ "url": "http://sandbox.mintlify.com" }], paths /plants and /plants/{id}, a /plant/webhook, and "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }. The real API lives at https://listenlabs.ai/api/public/... and authenticates with x-api-key / x-id headers — none of which appear in the spec.
Consequence: This is the single file an AI coding agent (or any client codegen tool) will trust most. An agent that ingests it will generate a client for a fictional plant store on sandbox.mintlify.com using bearer auth — wrong host, wrong endpoints, wrong auth scheme. Programmatic endpoint discovery is impossible; everything real is prose only.
The fix: Replace the template with a generated spec describing the actual /api/public/list_surveys, /responses/{link_id}, /responses/{link_id}/{response_id}, and /studies/{study_id}/questions endpoints, the x-api-key/x-id security schemes, and the listenlabs.ai server. Until it exists, remove it from llms.txt rather than advertise a decoy.
2. Auth page says the API key "only supports the /responses endpoints," but other documented endpoints require it (critical)
Location: /get-api-access (Authentication)
Problem: The page states: "Note that this method currently only supports the /responses endpoints." But the List Studies page (GET /api/public/list_surveys) and the Get Study Questions page (GET /api/public/studies/{study_id}/questions) both show curl ... -H 'x-api-key: ' — i.e. they require the API key on non- endpoints.
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Consequence: A developer reading the auth page first will assume list_surveys and studies/.../questions are unreachable with their key (or must use Google OAuth), and won't even attempt them. Conversely, someone following the endpoint pages can't tell whether the key is officially supported there or working by accident. Either way the auth contract is unknowable.
The fix: State exactly which endpoints accept x-api-key. If it now covers list/questions/responses, delete the "/responses only" caveat; if it doesn't, fix the curl examples on those pages to show the supported auth method.
3. study_id parameter name contradicts the value you must actually pass (link_id) (critical)
Location: /get-study-questions and /data-map
Problem: Get Study Questions documents GET /api/public/studies/{study_id}/questions with the path param described as "The unique ID of the study." But the page's own example passes a link slug — curl 'https://listenlabs.ai/api/public/studies/my-study/questions' — and the Data Map join-key table confirms: for Study→Question the join field is study_id with the note "Uses the link_id value," and every traversal example calls /api/public/studies/{link_id}/questions.
Consequence: The study object returns both an id (a UUID like 12345678-0000-...) and a link_id (e.g. study-1). A developer or agent who reads "unique ID of the study" will pass the UUID id and get a failed lookup, because the endpoint actually wants the link_id. The parameter name actively points at the wrong field.
The fix: Rename the path parameter to link_id and describe it as "the study's link ID (same value used in /responses/{link_id})," matching the Data Map and the working example.
4. Welcome page links a promoted "Mission Control" feature (and Emotional Intelligence) to pages that 404 (significant)
Location: /get-started/index
Problem: The Welcome page links Mission Control to /insights-and-reports/mission-control (linked twice) — a page that returns HTTP 404 and has no docs page anywhere. It also links Emotional Intelligence to /insights-and-reports/emotional-understanding, which 404s; the real page is /insights-and-reports/emotional-intelligence.
Consequence: The first page a new user reads promotes a flagship "cross-study knowledge base" (Mission Control) as a Key Feature and in the "Compound Your Knowledge" step, then sends them to a dead end with zero documentation. The Emotional Intelligence link is broken purely by a slug mismatch, so the one feature that does have a page is unreachable from the entry point. (Severity: a broken-link + missing-page defect on the entry page — serious for onboarding, but it does not break API clients the way Issues 1–3 do.)
The fix: Create the Mission Control page (or remove the links until it exists), and repoint the Emotional Intelligence link to /insights-and-reports/emotional-intelligence.
5. Two competing Authentication pages, and the link to the missing "Method 2" content is dead (significant)
Location: /get-api-access and /request-api
Problem:/request-api is a near-duplicate of /get-api-access but truncated: it drops the entire "Method 2: Google Id Token" body and replaces it with an empty-anchor-text link ### [****](https://docs.listenlabs.ai/api-reference/authentication#method-2-google-id-token). That target path returns HTTP 404. So there are two auth pages with diverging content, and the only pointer to the Google ID Token method on one of them is a broken link with no visible link text.
Consequence: Developers who land on /request-api (it's listed in llms.txt as "Get API Access") never learn the Google OAuth x-id method exists, and the link that's supposed to fill the gap goes nowhere.
The fix: Consolidate to one Authentication page, redirect the other, and remove the dead /api-reference/authentication anchor.
6. API reference slugs and titles disagree with their content (significant)
Location: /endpoint, /method-1, and /llms.txt
Problem:llms.txt lists "List Studies — /endpoint.md" and "Endpoint — /method-1.md". The page at /endpoint is in fact "List Studies." The page at /method-1 has the generic H1 "Endpoint," but its body is the "Get Responses" reference (GET /api/public/responses/{link_id}, pagination params, answers_array). So slug, title, and content disagree across the API section, and one page's only title is the word "Endpoint."
Consequence: Agents and humans navigating by URL or by the llms.txt index can't predict what a page contains — /endpoint is List Studies, and /method-1 is the Get Responses reference titled "Endpoint." A generically-titled "Endpoint" page is invisible to search and gives an agent no signal about which operation it documents.
The fix: Give each endpoint a descriptive, content-matching slug and H1 (e.g. /api-reference/list-studies, /api-reference/get-responses), and update the llms.txt labels to match. (If a separate /get-responses page also exists, confirm the two don't drift — only one currently needs to carry the canonical Get Responses content.)
7. Collaborator role is defined two opposite ways, and an "Editor" role is referenced but never defined (significant)
Location: /get-started/studies-overview (FAQ) and /settings-and-management/account (Seat Types & Permissions)
Problem: The FAQ says "Collaborators have read-only acess to study results." The Seat Types page says "Collaborator: Can create and edit studies but cannot launch them" (reinforced by "New in February 2026: ... Collaborators can build, but only Researchers and Admins can launch"). Read-only and "can create and edit studies" are contradictory. Separately, the FAQ states "Editors cannot add other members," but no "Editor" role is defined anywhere — the Seat Types page lists Admin, Researcher, Collaborator, Manager, and Researcher (team).
Consequence: Admins provisioning seats can't tell whether assigning Collaborator grants edit rights or read-only viewing — a real access-control decision. References to a nonexistent "Editor" role compound the confusion about who can invite members.
The fix: Pick one Collaborator definition and use it on both pages; remove or define the "Editor" role so the taxonomy is consistent.
8. The number of supported languages changes on nearly every page (significant)
Problem: The platform's language support is stated as "90+ languages, and 40+ languages with voice moderation" (FAQ), "90+ supported languages" then "~100 languages" on the same Auto-Translations page, "90+ languages" (Languages: Complete List, transcription/analysis), "100+ languages" (Recruiting), "40+ languages" (Voice Interviewer), and "50+ languages" (Emotional Intelligence). Auto-Translations contradicts itself in its intro versus its own FAQ.
Consequence: A buyer evaluating market coverage, or a developer scoping which locales to launch in, gets four-plus different answers and no canonical list to rely on. The self-contradiction on a single page makes the number look unmaintained.
The fix: Establish one source of truth (the Complete List page), state distinct numbers for distinct capabilities — text translation vs. voice moderation vs. transcription/analysis — and reference that single figure everywhere else.
9. Voice Interviewer cross-link is missing a leading slash and resolves to a 404 (significant)
Problem: The link to Auto-Translations is written [**Localizing Your Study: Auto-Translations**](setup-to-launch/auto-translations) — a relative path with no leading slash. From this page it resolves to /setup-to-launch/setup-to-launch/auto-translations, which returns HTTP 404.
Consequence: The intended path between the two localization pages is broken; readers following "for text-based translation, see..." hit a dead page.
The fix: Change the href to the absolute /setup-to-launch/auto-translations.
10. MCP troubleshooting references tools and a field that no scraped MCP page documents (significant)
Location: /mcp-docs/troubleshooting and /mcp-docs/connect
Problem: Troubleshooting tells users that "get_study_analysis requires a completed analysis run. Check list_studies for has_analysis: true." Across the scraped MCP pages — Connect and Troubleshooting — there is no tool reference: Connect documents the server URL, transport, and OAuth token lifetimes but lists no tool names or schemas, so get_study_analysis, list_studies, and the has_analysis field appear for the first (and only) time inside a troubleshooting step.
Consequence: A developer wiring up the MCP server can't discover what tools the server exposes, what arguments they take, or what fields they return from the operational pages — they only learn two tool names exist when something breaks. Agents can't enumerate capabilities at all.
The fix: Add an MCP tool reference listing each tool (list_studies, get_study_analysis, etc.) with parameters and response fields including has_analysis, and link it from Connect and Troubleshooting.
11. Two endpoints give different deprecation guidance, and question_uuid is undocumented (significant)
Location: /method-1 (Get Responses) and /get-single-response
Problem: The question-identifier story is inconsistent across the two response endpoints. Get Responses documents question_id string deprecated — "Deprecated. Use answer_id instead." Get Single Response describes a deprecated field anonymously — "Deprecated. Use discussion_guide_question_id instead." — without naming which field it refers to. On top of that, the Get Single Response example transcript row returns "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001" (the same value as discussion_guide_question_id), but question_uuid is never listed in the documented field set.
Consequence: A developer parsing responses across both endpoints sees question_id, answer_id, discussion_guide_question_id, and an undocumented question_uuid, and gets two different "use X instead" answers — one endpoint steers deprecated IDs to answer_id, the other to discussion_guide_question_id. They can't tell which field is canonical, which is the deprecated one the docs warn about, or whether question_uuid is safe to depend on. The Data Map's join instructions (Question.id = Answer.discussion_guide_question_id) don't account for question_uuid at all.
The fix: Document question_uuid explicitly (state if it's the deprecated alias of discussion_guide_question_id), name the deprecated field in the Get Single Response prose, and reconcile the deprecation guidance so both endpoints point to the same canonical field.
12. llms-full.txt appears to be missing a page the index advertises (significant)
Location: /llms.txt and /llms-full.txt
Problem:llms.txt lists "Concept Testing — https://docs.listenlabs.ai/setup-to-launch/concept-testing.md", and that page exists live — but no Concept Testing content surfaced in the /llms-full.txt pull while every other indexed page did, indicating the page is absent from the full-text bundle.
Consequence: Agents that ingest the full-text bundle (the efficient path the file is designed for) appear to miss Concept Testing entirely, while the index claims it's covered. Silent omission is worse than an obvious gap.
The fix: Diff llms-full.txt against llms.txt; if Concept Testing is missing, regenerate the bundle to include every indexed page, and add a build check that the two stay in sync.
13. "Emotional Intelligence" and "Emotional Understanding" are used for the same feature, with two different benchmark claims (minor)
Problem: The page is titled "Emotional Intelligence" but the body switches to "Emotional Understanding analyzes behavioral signals..." — the same name as the broken Welcome-page slug. The benchmark is also stated two ways: "benchmarked against MELD for state-of-the-art accuracy," then "validated against academic benchmarks (CMU-MOSEI and MELD frameworks)."
Consequence: Readers (and search/agents) can't tell if "Emotional Understanding" is a separate feature or a renaming, and the inconsistent benchmark wording undercuts the technical claim.
The fix: Pick one product name and use it throughout; state the benchmark set once, consistently.
14. Recurring misspellings inside API reference and FAQ content (minor)
Problem: Errors appear in technical/reference text, not just prose: "lists all studys" / "Returns a list of studys" (List Studies, repeated), "responses that who's analysis is still in progress" (Get Responses), "read-only acess" (Studies Overview FAQ), and "Suprise" in the listed Ekman emotions (Emotional Intelligence).
Consequence: Misspellings in field/endpoint descriptions hurt in-site search and agent parsing (e.g. searching "studies" won't match "studys"), and erode confidence in the reference where precision matters most.
The fix: Run a spell/lint pass over the docs source, prioritizing API reference field descriptions.
15. MCP server exposes two "equivalent" URLs but examples only use one (minor)
Location: /mcp-docs/connect
Problem: The page says the Server URL is https://listenlabs.ai/mcp and "You can also use https://mcp.listenlabs.ai/mcp (equivalent endpoint)," but every concrete instruction (ChatGPT/Claude/Codex, e.g. codex mcp add listenlabs --url https://listenlabs.ai/mcp) and the OAuth redirect (https://listenlabs.ai/mcp/authorize) hard-code only the first.
Consequence: Users can't tell whether mcp.listenlabs.ai is fully supported (including the OAuth /authorize redirect) or a secondary alias, creating uncertainty about which to configure.
The fix: State which URL is canonical, confirm OAuth works identically on both, or drop the secondary mention.
16. Every curl example ships an empty API key with no placeholder (minor)
Location: /endpoint (List Studies) and /get-study-questions
Problem: The copy-paste curl examples send an empty auth header: -H 'x-api-key: '. There is no placeholder such as x-api-key: YOUR_API_KEY and nothing marking the value as something the reader must supply.
Consequence: A developer or agent that copies the example verbatim sends an empty x-api-key header and gets a 401 with no indication that the blank value is the cause — the example is syntactically runnable but guaranteed to fail.
The fix: Use an explicit, clearly-marked placeholder (e.g. -H 'x-api-key: YOUR_API_KEY') in every curl example, consistent across the endpoint pages.
What they do well
The Data Map page is a genuinely strong artifact: explicit join-key table and step-by-step traversal examples make multi-endpoint stitching clear (and it's what exposes the study_id/link_id truth).
API responses are shown with realistic, fully-populated JSON examples (transcript rows, signed audio URLs with stated 1-hour expiry, pagination defaults), which is more than many prose-only platforms provide.
MCP auth is documented with concrete token lifetimes (access 1h, refresh 30d) and a stated stateless Streamable-HTTP transport — useful operational detail.
Top 3 recommendations
Replace the Plant Store OpenAPI spec with a real, generated spec for the listenlabs.ai/api/public endpoints and the x-api-key/x-id auth schemes — this is the highest-leverage fix for both humans and agents.
Resolve the auth and parameter contradictions: clarify which endpoints accept x-api-key, fix the empty-key curl placeholders, and rename the questions path param from study_id to link_id to match the value the API actually requires.
Fix the confirmed-dead internal links and create the missing pages (Mission Control, the Emotional Intelligence slug, the /request-api Method 2 anchor, the slashless Auto-Translations link), then add a link-checker and an llms.txt/llms-full.txt sync check to CI.