Feedback: api-reference-lemur-get-response

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/lemur/get-response
Category: api-reference
Generated: 05/08/2025, 4:32:14 pm

---

Claude Sonnet 4 Feedback

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

Technical Documentation Analysis & Feedback

This API reference documentation needs significant improvements to meet professional standards. Here’s my detailed analysis:

🚨 Critical Issues

1. Missing Response Schema

Problem: No response body structure is documented. Impact: Developers can’t understand what data they’ll receive. Solution: Add complete response schema with field descriptions.

// Example of what should be included:
{
  "request_id": "string",
  "status": "completed | processing | error",
  "response": "string",
  "created": "2023-08-05T10:30:00Z",
  "completed": "2023-08-05T10:35:00Z"
}

2. Redundant Examples

Problem: 8 identical curl commands with inconsistent parameter formatting. Impact: Clutters documentation and creates confusion. Solution: Provide 2-3 diverse, meaningful examples.

📝 Specific Improvements Needed

Structure & Organization

# Retrieve LeMUR Response

## Overview
Brief description of what LeMUR is and when you'd use this endpoint.

## Authentication
Details about API key requirements and format.

## Request
### Endpoint
### Path Parameters
### Headers

## Response
### Success Response (200)
### Error Responses
### Response Fields

## Examples
### Basic Request
### With Response
### Error Handling

## Related Endpoints
## Rate Limits

Missing Information

1. Authentication Details

   • API key format (Bearer token? Header format?)
   • Required permissions/scopes

2. Response Field Descriptions

   | Field | Type | Description |
   |-------|------|-------------|
   | request_id | string | Unique identifier for the LeMUR request |
   | status | string | Current status: `completed`, `processing`, `error` |
   | response | string | The generated LeMUR response text |

3. Error Response Bodies

   // 404 Error Example
   {
     "error": "Request not found",
     "message": "No LeMUR request found with ID: abc123"
   }

4. Rate Limiting Information

   • Requests per minute/hour
   • Rate limit headers returned

Better Examples Needed

Replace the repetitive examples with:

# Basic request
curl -X GET "https://api.assemblyai.com/lemur/v3/abc123def456" \
     -H "Authorization: Bearer YOUR_API_KEY"

# With verbose output to see headers
curl -v -X GET "https://api.assemblyai.com/lemur/v3/abc123def456" \
     -H "Authorization: Bearer YOUR_API_KEY"

Add response examples:

// Successful response
{
  "request_id": "abc123def456",
  "status": "completed",
  "response": "Based on the transcript analysis...",
  "created": "2023-08-05T10:30:00Z",
  "completed": "2023-08-05T10:35:00Z"
}

Clarity Issues

1. Vague descriptions: “LeMUR response that was previously generated” - what is LeMUR?
2. Inconsistent parameter format: Mix of {request_id} and :request_id
3. Generic error descriptions: “Bad request” without specifics

🎯 User Experience Improvements

Add Context

## When to Use This Endpoint
Use this endpoint to retrieve the results of a LeMUR (Language Model Understanding & Reasoning) request after it has been processed. LeMUR requests are asynchronous, so you'll need to poll this endpoint or use webhooks to get results.

Add Workflow Guidance

## Typical Workflow
1. Submit a LeMUR request using the `/lemur/v3/task` endpoint
2. Save the `request_id` from the response
3. Poll this endpoint until `status` is `completed` or `error`
4. Process the `response` field containing your results

Common Scenarios

## Common Use Cases
- Check if a long-running LeMUR task has completed
- Retrieve results from a previous session
- Implement retry logic for failed requests

🔧 Technical Enhancements

Add SDK Examples

# Python SDK example
import assemblyai as aai

client = aai.Client(api_key="YOUR_API_KEY")
response = client.lemur.get_response("abc123def456")
print(response.status)

Add Status Codes Details

| Code | Meaning | Action Required |
|------|---------|----------------|
| 200 | Success | Process the response |
| 404 | Request ID not found | Verify the request_id |
| 429 | Rate limited | Implement backoff strategy |

📋 Quick Win Checklist

• Remove 7 duplicate curl examples
• Add response schema with field descriptions
• Include example response bodies
• Explain what LeMUR is in 1-2 sentences
• Fix parameter format consistency
• Add authentication details
• Include at least one error response example
• Add links to related endpoints (create LeMUR request)

This documentation needs substantial work to be production-ready. The current version would likely frustrate developers and increase support tickets.

---