> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/save-transcript-draft/.

# Save the transcript draft

Saves an arbitrary JSON object (`data`, up to 900,000 bytes) as the generation's transcript draft, with optional `revision` checking to prevent lost updates.

PUT `https://api.diffio.ai/v2/projects/{project_id}/generations/{generation_id}/transcript/draft`

- Key scope: `generations:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: JSON

## Request

Send `data` (any JSON object up to 900,000 bytes) and optional `revision` from the last read.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |
| `generation_id` | string | Yes | Unique identifier of the generation within the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |

### Body fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | Yes | Arbitrary JSON object holding your editor's draft state (at most `900000` bytes as compact UTF-8 JSON); stored and returned verbatim. |
| `revision` | string | No | Optional opaque `revision` last read from `GET .../transcript/draft`. Refuses stale saves with `409` (`revision_conflict`) and `details.current_revision`; omit to overwrite unconditionally. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

draft = client.transcripts.save_draft(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
    data={"cursor": 12, "removed": ["w3"]},
    revision="0",
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const draft =
  await client.transcripts.saveDraft(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "ce832a32-a1ce-516a-b8bd-75457bd8517f",
    {
      data: {
        "cursor": 12,
        "removed": ["w3"],
      },
      revision: "0",
    },
  )
```

**cURL**

```bash
curl -X PUT "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations/ce832a32-a1ce-516a-b8bd-75457bd8517f/transcript/draft" \
  -H "Authorization: Bearer $DIFFIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "cursor": 12,
      "removed": [
        "w3"
      ]
    },
    "revision": "0"
  }'
```

**JSON: JSON body**

```json
{
  "data": {
    "cursor": 12,
    "removed": [
      "w3"
    ]
  },
  "revision": "0"
}
```

## Response

Returns the saved `transcript_draft` with its new `revision`.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `object` | string | Always | Resource type, always `"transcript_draft"`. |
| `project_id` | string | Always | Identifier of the parent project. |
| `generation_id` | string | Always | Identifier of the generation. |
| `revision` | string | Always | Opaque revision string (`"0"` before the first save); send back when saving or deleting to detect concurrent edits. |
| `data` | object \| null | Always | Saved JSON object exactly as sent to `PUT .../transcript/draft`, or `null` when no draft is saved. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the current draft was first created, or `null` when empty. |
| `updated_at` | string \| null | Always | ISO 8601 UTC timestamp when the draft was last saved, or `null` when empty. |

## Example response (200)

**Successful response**

```json
{
  "object": "transcript_draft",
  "project_id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "generation_id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "revision": "1",
  "data": {
    "cursor": 12,
    "removed": [
      "w3"
    ]
  },
  "created_at": "2026-11-13T00:33:51.366709Z",
  "updated_at": "2026-11-13T00:33:51.366709Z"
}
```

## Return codes

- `200` Draft saved and returned with a new `revision`.
- `400`
  - Malformed JSON: [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json)
  - Missing `data`: [`missing_field`](https://diffio.ai/docs/api-reference/errors/#missing_field)
  - `data` is not a JSON object or `revision` is not one a draft answer gave: [`invalid_field`](https://diffio.ai/docs/api-reference/errors/#invalid_field)
  - Oversized header: [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `generations:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` Project not found, or generation not found. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found) [`generation_not_found`](https://diffio.ai/docs/api-reference/errors/#generation_not_found)
- `409` Sent `revision` does not match the current revision, reported in `details.current_revision`. [`revision_conflict`](https://diffio.ai/docs/api-reference/errors/#revision_conflict)
- `413` `data` exceeds `900,000` bytes when serialized as compact UTF-8 JSON. [`transcript_draft_too_large`](https://diffio.ai/docs/api-reference/errors/#transcript_draft_too_large)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- On `409` (`revision_conflict`), read [Get the transcript draft](https://diffio.ai/docs/api-reference/get-transcript-draft/) again, merge changes, and retry with `details.current_revision`.
- Saving a draft only stores editor state; it never alters audio or starts a billable edit until you call [Edit a generation's transcript](https://diffio.ai/docs/api-reference/create-transcript-edit/).

## Related pages

- Previous: [Get the transcript draft](https://diffio.ai/docs/api-reference/get-transcript-draft/): Read the saved JSON editor draft and compare-and-swap revision for a generation's transcript.
- Next: [Delete the transcript draft](https://diffio.ai/docs/api-reference/delete-transcript-draft/): Delete a generation's saved transcript editor draft with optional revision checking.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [Billing](https://diffio.ai/docs/overview/administration/billing/): Starter credit, metering and invoices.
