For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/save-transcript-draft.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

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:/
- 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
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: 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 | Required: 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 | Required: 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. |
Request
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",
)Response
Returns the saved transcript_draft with its new revision.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#object | string | Always | Resource type, always "transcript_draft".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. |
Response 200OK.
{
"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
200OK.Draft saved and returned with a newrevision.400Bad request.Malformed JSON, or 3 more causes
- Malformed JSON
- Missing
data datais not a JSON object orrevisionis not one a draft answer gave- Oversized header
invalid_jsonmissing_fieldinvalid_fieldinvalid_header403Forbidden: the key lacks permission.Key is inactive or lacksgenerations:write.permission_denied404Not found.Project not found, or generation not found.project_not_foundgeneration_not_found409Conflict: see error.code for which one.Sentrevisiondoes not match the current revision, reported indetails.current_revision.revision_conflict413Payload too large.dataexceeds900,000bytes when serialized as compact UTF-8 JSON.transcript_draft_too_large401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. 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 401Unauthorized: the API key is missing or invalid.:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
- On
409(revision_conflict), read Get the transcript draft again, merge changes, and retry withdetails.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.