Feedback: api-reference-lemur-question-answer

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/lemur/question-answer
Category: api-reference
Generated: 05/08/2025, 4:32:15 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:32:14 pm

Technical Documentation Analysis: LeMUR Question-Answer API

Overall Assessment

This documentation has significant gaps that would frustrate developers trying to implement the API. While it shows the endpoint and basic usage, it lacks essential technical details and has structural issues.

Critical Missing Information

1. Request Body Specification

Issue: No formal schema or parameter documentation Impact: Developers can’t understand what parameters are required vs. optional

Recommendation: Add a complete request body schema:

## Request Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `final_model` | string | Yes | AI model to use (e.g., "anthropic/claude-sonnet-4-20250514") |
| `questions` | array | Yes | Array of question objects (max 10) |
| `transcript_ids` | array | Conditional | Required if not using `context`. Array of transcript IDs |
| `context` | string | Conditional | Required if not using `transcript_ids`. Custom context text |
| `max_output_size` | integer | No | Maximum response length (default: 2000, max: 100000) |
| `temperature` | number | No | Response creativity (0.0-1.0, default: 0.0) |

2. Response Body Details

Issue: Only HTTP status codes listed, no response structure Impact: Developers don’t know what data they’ll receive

Recommendation: Add response schema and examples:

## Response Schema

### Success Response (200)
```json
{
  "response": [
    {
      "question": "Where are there wildfires?",
      "answer": "US, CA"
    }
  ],
  "request_id": "abc123-def456",
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567
  }
}

Error Response Examples

{
  "error": "Invalid transcript_id",
  "code": "invalid_request"
}

Structural Issues

1. Redundant Examples

Issue: 8 nearly identical curl examples with placeholder values Impact: Clutters documentation without adding value

Recommendation: Replace with 2-3 meaningful examples:

• Basic question with transcript_ids
• Multiple questions with answer_options
• Using custom context instead of transcript_ids

2. Missing Prerequisites Section

Issue: No guidance on getting transcript IDs or API keys Impact: New users can’t get started

Recommendation: Add prerequisites:

## Prerequisites

1. **API Key**: Get your API key from the [AssemblyAI Dashboard](https://app.assemblyai.com/)
2. **Transcript ID**: First transcribe audio using the [Transcription API](/api-reference/transcription)
3. **Authentication**: Include your API key in the Authorization header

Content Clarity Issues

1. Parameter Relationships

Issue: Unclear when to use transcript_ids vs context Impact: Users don’t understand the two different usage patterns

Recommendation: Add clear explanation:

## Usage Patterns

### Pattern 1: Analyze Existing Transcripts
Use `transcript_ids` to ask questions about previously transcribed audio:
```json
{
  "transcript_ids": ["transcript_123"],
  "questions": [{"question": "What was discussed?"}]
}

Pattern 2: Analyze Custom Text

Use context to ask questions about any text content:

{
  "context": "Meeting notes: We discussed the Q4 budget...",
  "questions": [{"question": "What budget items were mentioned?"}]
}

2. Question Object Structure

Issue: Question object parameters not documented Impact: Users don’t understand answer_format and answer_options

Recommendation: Document question object properties:

### Question Object Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | Yes | The question to ask |
| `answer_format` | string | No | Desired format for the answer (e.g., "List of countries in ISO format") |
| `answer_options` | array | No | Limit responses to specific options |

User Experience Improvements

1. Add Quick Start Guide

## Quick Start

1. **Get a transcript ID** by transcribing audio
2. **Ask a question** about the transcript:

```bash
curl -X POST https://api.assemblyai.com/lemur/v3/generate/question-answer \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript_ids": ["your_transcript_id"],
    "questions": [{"question": "What are the main topics discussed?"}]
  }'

2. Add Common Use Cases

## Common Use Cases

- **Meeting Analysis**: "Were all agenda items covered?"
- **Call Scoring**: "How satisfied was the customer (1-10)?"
- **Content Extraction**: "What action items were mentioned?"
- **Sentiment Analysis**: "What was the overall tone?"

3. Add Error Handling Guide

## Error Handling

| Status Code | Common Causes | Solutions |
|-------------|---------------|-----------|
| 400 | Invalid transcript_id, missing required fields | Verify transcript exists and request format |
| 401 | Invalid API key | Check API key in Authorization header |
| 429 | Rate limit exceeded | Implement exponential backoff |

Technical Accuracy Issues

1. Authentication Format

Issue: Shows Authorization: <apiKey> Impact: Unclear if this needs “Bearer” prefix or specific format

Recommendation: Clarify: Authorization: YOUR_API_KEY (no Bearer prefix needed)

2. Model Availability

Issue: No list of available models Impact: Users don’t know their options

Recommendation: Add supported models list or link to models documentation

Priority Recommendations

1. HIGH: Add complete request/response schemas
2. HIGH: Replace redundant examples with meaningful ones
3. HIGH: Add prerequisites and quick start section
4. MEDIUM: Document question object parameters
5. MEDIUM: Add error handling guidance
6. LOW: Add use cases and best practices

These improvements would transform this from a basic endpoint reference into comprehensive, user-friendly documentation that enables successful implementation.

---