> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Summary

> Generate an AI-powered summary from a transcription

Generate a structured summary from a completed transcription. The transcription must be in `completed` status.

You can create multiple summaries for the same transcription using different templates.

Use [webhooks](/webhooks/overview) to receive real-time notifications when the summary completes, or poll the [Get Summary](/api-reference/summaries/get) endpoint.

## Authentication

Requires an [API key](/authentication) with `summaries:write` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.bota.dev/v1/summaries \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "transcription_id": "txn_abc123",
      "template_id": "tmpl_sales_call",
      "provider": "gemini"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.bota.dev/v1/summaries', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      transcription_id: 'txn_abc123',
      template_id: 'tmpl_sales_call',
      provider: 'gemini', // optional: gemini | openai | claude
    }),
  });

  const summary = await response.json();
  console.log(summary.id); // 'sum_abc123'
  console.log(summary.status); // 'pending'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.bota.dev/v1/summaries',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      json={
          'transcription_id': 'txn_abc123',
          'template_id': 'tmpl_sales_call',
          'provider': 'gemini',  # optional: gemini | openai | claude
      },
  )

  summary = response.json()
  print(summary['id'])  # 'sum_abc123'
  ```
</RequestExample>

## Request Body

<ParamField body="transcription_id" type="string" required>
  The transcription's unique identifier (e.g., `txn_abc123`). Must be in `completed` status.
</ParamField>

<ParamField body="template_id" type="string">
  System template ID to use. One of: `tmpl_general_notes`, `tmpl_sales_call`, `tmpl_clinical_soap`, `tmpl_legal_memo`.

  Either `template_id` or `prompt` is required, but not both.
</ParamField>

<ParamField body="prompt" type="string">
  Custom prompt for one-off summaries. Use this instead of `template_id` for custom summarization.

  Must be 10-10,000 characters. Either `template_id` or `prompt` is required, but not both.
</ParamField>

<ParamField body="provider" type="string">
  LLM provider to use for summarization. If not specified, uses the system default.

  | Provider | Description                                     |
  | -------- | ----------------------------------------------- |
  | `gemini` | Google Gemini 2.0 Flash (default) - JSON output |
  | `openai` | OpenAI GPT-4o - JSON mode                       |
  | `claude` | Anthropic Claude Sonnet 4 - Structured output   |
</ParamField>

## Response

Returns the newly created summary object with `pending` status.

<ResponseExample>
  ```json 202 theme={null}
  {
    "id": "sum_abc123",
    "project_id": "proj_xyz",
    "transcription_id": "txn_abc123",
    "status": "pending",
    "template_id": "tmpl_sales_call",
    "provider": "gemini",
    "custom_prompt": null,
    "output": null,
    "error_message": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2025-01-15T10:10:00Z",
    "updated_at": "2025-01-15T10:10:00Z"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Either template_id or prompt is required, but not both"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Transcription not found"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field              | Type           | Description                                                       |
| ------------------ | -------------- | ----------------------------------------------------------------- |
| `id`               | string         | The summary's unique identifier (e.g., `sum_abc123`)              |
| `project_id`       | string         | The project this summary belongs to                               |
| `transcription_id` | string         | The transcription this summary was generated from                 |
| `status`           | string         | Current status: `pending`, `processing`, `completed`, or `failed` |
| `template_id`      | string \| null | The template used, if any                                         |
| `provider`         | string         | LLM provider used (e.g., `gemini`, `openai`, `claude`)            |
| `custom_prompt`    | string \| null | The custom prompt used, if any                                    |
| `output`           | object \| null | Structured summary output (populated on completion)               |
| `error_message`    | string \| null | Error message if the summary failed                               |
| `started_at`       | string \| null | ISO 8601 timestamp when processing started                        |
| `completed_at`     | string \| null | ISO 8601 timestamp when the summary completed or failed           |
| `created_at`       | string         | ISO 8601 timestamp when the summary was created                   |
| `updated_at`       | string         | ISO 8601 timestamp when the summary was last updated              |

## Templates

Bota provides four built-in system templates optimized for different use cases:

| Template ID          | Target Industry     | Output Format                                                          |
| :------------------- | :------------------ | :--------------------------------------------------------------------- |
| `tmpl_general_notes` | General meetings    | Key points, action items, participants, decisions, overview            |
| `tmpl_sales_call`    | Sales calls         | Pain points, budget, timeline, next steps, sentiment, deal probability |
| `tmpl_clinical_soap` | Healthcare          | SOAP notes (Subjective, Objective, Assessment, Plan)                   |
| `tmpl_legal_memo`    | Legal consultations | Facts, issues, analysis, conclusion, parties involved                  |

See [Summary Templates](/api-reference/summaries/templates) for detailed output schemas.

## Custom Prompts

For custom summarization, use the `prompt` parameter instead of `template_id`:

```bash theme={null}
curl -X POST https://api.bota.dev/v1/summaries \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_id": "txn_abc123",
    "prompt": "Extract all technical requirements and action items from this conversation. Format as a bulleted list."
  }'
```

## Summary Status

| Status       | Description                                             |
| :----------- | :------------------------------------------------------ |
| `pending`    | Job queued, waiting to start                            |
| `processing` | Summary generation in progress                          |
| `completed`  | Summary generated successfully                          |
| `failed`     | Summary generation failed (check `error_message` field) |

## Auto-Summary

Instead of calling this endpoint manually, you can enable **auto-summary** to automatically generate a summary whenever a transcription completes.

Configure via the [hierarchical config system](/guides/hierarchical-config):

```bash theme={null}
curl -X PUT https://api.bota.dev/v1/projects/proj_xxx/config/processing \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "auto_summary": {
      "enabled": true,
      "provider": "gemini",
      "template": "general_notes"
    }
  }'
```

Auto-summary works with auto-transcription for a fully automated pipeline: upload → transcribe → summarize. See the [Auto-Processing Guide](/guides/auto-processing) for full details.

## Webhooks (Recommended)

For production use, subscribe to webhook events instead of polling:

* [`summary.started`](/webhooks/events#summarystarted) - Processing begins
* [`summary.completed`](/webhooks/events#summarycompleted) - Summary generated successfully
* [`summary.failed`](/webhooks/events#summaryfailed) - Summary generation failed

See [Webhooks Overview](/webhooks/overview) for setup instructions.

<Note>
  Summary generation typically takes 5-15 seconds, depending on transcript length and template complexity.
</Note>