Feedback: api-reference-lemur-task

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/lemur/task
Category: api-reference
Generated: 05/08/2025, 4:31:38 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:31:37 pm

Documentation Analysis & Improvement Recommendations

This API documentation has several critical issues that will frustrate developers. Here’s my detailed analysis with actionable improvements:

🚨 Critical Missing Information

1. Request Body Schema

Issue: No documentation of required/optional parameters Fix: Add a complete request schema table:

## Request Body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Your custom LLM prompt for analyzing the transcript |
| `final_model` | string | Yes | The LLM model to use (see supported models below) |
| `transcript_ids` | array[string] | No | Array of transcript IDs to analyze. Required if not using `input_text` |
| `input_text` | string | No | Raw text input instead of transcript IDs |
| `max_output_size` | integer | No | Maximum response length (default: 2000, max: 4000) |
| `temperature` | float | No | Model creativity (0.0-1.0, default: 0.0) |

2. Response Schema

Issue: Only HTTP status codes listed, no response structure Fix: Document the actual response format:

## Response Schema

**Success Response (200)**
```json
{
  "request_id": "string",
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567
  },
  "response": "string"  // The LLM's response to your prompt
}

Error Response (4xx/5xx)

{
  "error": "string",
  "message": "string",
  "request_id": "string"
}

🔧 Structure & Clarity Issues

3. Redundant Examples

Issue: 8 nearly identical curl examples with placeholder data Fix: Replace with 2-3 meaningful, diverse examples:

## Examples

### Basic Task with Transcript Analysis
```shell
curl -X POST https://api.assemblyai.com/lemur/v3/generate/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize the key action items and decisions made in this meeting",
    "final_model": "anthropic/claude-sonnet-4-20250514",
    "transcript_ids": ["64nygnr62k-405c-4ae8-8a6b-d90b40ff3cce"]
  }'

Custom Analysis with Raw Text

curl -X POST https://api.assemblyai.com/lemur/v3/generate/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract all mentioned dates and events, format as a timeline",
    "final_model": "anthropic/claude-sonnet-4-20250514",
    "input_text": "Yesterday we discussed the Q4 launch...",
    "max_output_size": 1500,
    "temperature": 0.3
  }'

4. Add Prerequisites Section

## Prerequisites

1. **API Key**: Get your API key from the [AssemblyAI Dashboard](https://assemblyai.com/dashboard)
2. **Transcript ID**: If using `transcript_ids`, ensure your transcript is completed first
3. **LeMUR Access**: This endpoint requires LeMUR access on your account

📝 Missing Context & Information

5. Supported Models

Issue: No documentation of available models Fix: Add supported models section:

## Supported Models

| Model ID | Provider | Description |
|----------|----------|-------------|
| `anthropic/claude-sonnet-4-20250514` | Anthropic | Latest Claude Sonnet model |
| `openai/gpt-4` | OpenAI | GPT-4 model |
| `openai/gpt-3.5-turbo` | OpenAI | GPT-3.5 Turbo model |

6. Rate Limits & Quotas

## Rate Limits

- **Requests**: 100 requests per minute
- **Token Usage**: Varies by plan (check your dashboard)
- **Concurrent Requests**: 10 maximum

7. Error Handling Guide

## Common Error Scenarios

| Status | Cause | Solution |
|--------|-------|----------|
| 400 | Missing required parameters | Check request body schema |
| 401 | Invalid API key | Verify your API key is correct |
| 404 | Transcript not found | Ensure transcript ID exists and is completed |
| 429 | Rate limit exceeded | Implement exponential backoff |

🎯 User Experience Improvements

8. Add Workflow Context

## Typical Workflow

1. **Upload & Transcribe**: First transcribe your audio using the [Transcription API](link)
2. **Wait for Completion**: Ensure transcript status is `completed`
3. **Run LeMUR Task**: Use the transcript ID with your custom prompt
4. **Process Results**: Handle the structured response

9. Best Practices Section

## Best Practices

- **Prompt Design**: Be specific and clear in your prompts
- **Token Management**: Monitor token usage to control costs
- **Error Handling**: Always implement retry logic for production use
- **Temperature Setting**: Use 0.0 for consistent results, higher values for creativity

10. Quick Start Example

Add a complete, copy-paste ready example at the beginning showing the most common use case.

🔗 Navigation & References

11. Add Cross-References

• Link to Transcription API documentation
• Link to LeMUR overview/concepts
• Link to authentication guide
• Link to SDKs and client libraries

This documentation currently provides minimal value to developers. Implementing these improvements would transform it into a comprehensive, developer-friendly resource that reduces support tickets and improves adoption.

---