Deliverable Python SDK

Agent Skill

Let an agent scaffold this for you

Install the TurboDocx Quickstart Skill and let Claude Code, Cursor, Copilot, Codex, or any agent that speaks the Agent Skills standard install the SDK, wire it into your app, and write a working Deliverable integration end-to-end.

View on GitHubFull install guide →

bash — turbodocx

$npx skills add TurboDocx/quickstart

# then, inside your agent:›/turbodocx-sdk deliverable

The official TurboDocx Deliverable SDK for Python applications. Generate documents from templates with dynamic variable injection, download source files and PDFs, and manage deliverables programmatically with async/await patterns and comprehensive error handling. Available on PyPI as turbodocx-sdk.

Installation

pip

pip install turbodocx-sdk

Poetry

poetry add turbodocx-sdk

Pipenv

pipenv install turbodocx-sdk

Requirements

• Python 3.9+
• httpx (installed automatically)

---

Configuration

from turbodocx_sdk import Deliverable
import os

# Configure globally (recommended)
Deliverable.configure(
    api_key=os.environ["TURBODOCX_API_KEY"],  # Required: Your TurboDocx API key
    org_id=os.environ["TURBODOCX_ORG_ID"],    # Required: Your organization ID
    # base_url="https://api.turbodocx.com"    # Optional: Override base URL
)

No Sender Email Required

Unlike TurboSign, the Deliverable module only requires api_key and org_id: no sender email or name is needed.

Environment Variables

# .env
TURBODOCX_API_KEY=your_api_key_here
TURBODOCX_ORG_ID=your_org_id_here

API Credentials Required

Both api_key and org_id parameters are required for all API requests. To get your credentials, follow the Get Your Credentials steps from the SDKs main page.

---

Quick Start

Generate a document from a template

import asyncio
import json
from turbodocx_sdk import Deliverable
import os

Deliverable.configure(
    api_key=os.environ["TURBODOCX_API_KEY"],
    org_id=os.environ["TURBODOCX_ORG_ID"]
)

async def generate_report():
    # Generate a document from a template with variables
    result = await Deliverable.generate_deliverable(
        name="Q1 Report",
        template_id="your-template-id",
        variables=[
            {"placeholder": "{CompanyName}", "text": "Acme Corporation", "mimeType": "text"},
            {"placeholder": "{Date}", "text": "2026-03-12", "mimeType": "text"},
        ],
        description="Quarterly business report",
        tags=["reports", "quarterly"],
    )

    print("Result:", json.dumps(result, indent=2))

asyncio.run(generate_report())

Download and manage deliverables

import asyncio
from turbodocx_sdk import Deliverable
import os

Deliverable.configure(
    api_key=os.environ["TURBODOCX_API_KEY"],
    org_id=os.environ["TURBODOCX_ORG_ID"]
)

async def manage_deliverables():
    # List deliverables with pagination
    items = await Deliverable.list_deliverables(limit=10, show_tags=True)
    print(f"Total: {items['totalRecords']}")

    # Get deliverable details
    details = await Deliverable.get_deliverable_details("deliverable-uuid")
    print(f"Name: {details['name']}")

    # Download source file (DOCX/PPTX)
    source_bytes = await Deliverable.download_source_file("deliverable-uuid")
    with open("report.docx", "wb") as f:
        f.write(source_bytes)

    # Download PDF
    pdf_bytes = await Deliverable.download_pdf("deliverable-uuid")
    with open("report.pdf", "wb") as f:
        f.write(pdf_bytes)

    # Update deliverable
    await Deliverable.update_deliverable_info(
        "deliverable-uuid",
        name="Q1 Report - Final",
        description="Final quarterly business report",
    )

    # Delete deliverable
    await Deliverable.delete_deliverable("deliverable-uuid")

asyncio.run(manage_deliverables())

---

Variable Types

The Deliverable module supports four variable types for template injection:

1. Text Variables

Inject plain text values into template placeholders:

variables = [
    {"placeholder": "{CompanyName}", "text": "Acme Corporation", "mimeType": "text"},
    {"placeholder": "{Date}", "text": "2026-03-12", "mimeType": "text"},
]

2. HTML Variables

Inject rich HTML content with formatting:

variables = [
    {
        "placeholder": "{Summary}",
        "text": "<p>This is a <strong>formatted</strong> summary with <em>rich text</em>.</p>",
        "mimeType": "html",
    },
]

3. Image Variables

Inject images by providing a URL or base64-encoded content:

variables = [
    {
        "placeholder": "{Logo}",
        "text": "https://example.com/logo.png",
        "mimeType": "image",
    },
]

4. Markdown Variables

Inject markdown content that gets converted to formatted text:

variables = [
    {
        "placeholder": "{Notes}",
        "text": "## Key Points\n- First item\n- Second item\n\n**Important:** Review before submission.",
        "mimeType": "markdown",
    },
]

Variable Stack

For repeating content (e.g., table rows), use variableStack instead of text to provide multiple values for the same placeholder. See the Types section for details.

---

API Reference

Async snippets

The snippets below are partial and run inside an async function. They assume you have already called Deliverable.configure(...) and that asyncio and json are imported (import asyncio, json). For a complete runnable script, wrap the calls in async def main(): ... and run with asyncio.run(main()), as shown in Quick Start.

Configure

Configure the SDK with your API credentials and organization settings.

Deliverable.configure(
    api_key: Optional[str] = None,                   # API key (or use access_token)
    access_token: Optional[str] = None,              # OAuth2 access token (alternative to api_key)
    base_url: str = "https://api.turbodocx.com",     # Optional: API base URL
    org_id: Optional[str] = None,                    # Required: Your organization ID
)

API Credentials Required

All parameters are optional and keyword-only. Either api_key or access_token must be provided for authentication, and org_id is required for all Deliverable operations (enforced at runtime). To get your credentials, follow the Get Your Credentials steps from the SDKs main page.

Generate deliverable

Generate a new document from a template with variable substitution.

result = await Deliverable.generate_deliverable(
    name="Q1 Report",
    template_id="your-template-id",
    variables=[
        {"placeholder": "{CompanyName}", "text": "Acme Corp", "mimeType": "text"},
        {"placeholder": "{Date}", "text": "2026-03-12", "mimeType": "text"},
    ],
    description="Quarterly business report",
    tags=["reports", "quarterly"],
)

print("Result:", json.dumps(result, indent=2))

List deliverables

List deliverables with pagination, search, and filtering.

items = await Deliverable.list_deliverables(
    limit=10,
    offset=0,
    query="report",
    show_tags=True,
)

print("Result:", json.dumps(items, indent=2))

Get deliverable details

Retrieve the full details of a single deliverable, including variables and fonts.

details = await Deliverable.get_deliverable_details("deliverable-uuid", show_tags=True)

print("Result:", json.dumps(details, indent=2))

Update deliverable info

Update a deliverable's name, description, or tags.

result = await Deliverable.update_deliverable_info(
    "deliverable-uuid",
    name="Q1 Report - Final",
    description="Final quarterly business report",
    tags=["reports", "final"],
)

print("Result:", json.dumps(result, indent=2))

Delete deliverable

Soft-delete a deliverable.

result = await Deliverable.delete_deliverable("deliverable-uuid")

print("Result:", json.dumps(result, indent=2))

Download source file

Download the original source file (DOCX or PPTX).

source_bytes = await Deliverable.download_source_file("deliverable-uuid")

# Save to file
with open("report.docx", "wb") as f:
    f.write(source_bytes)

Download PDF

Download the PDF version of a deliverable.

pdf_bytes = await Deliverable.download_pdf("deliverable-uuid")

# Save to file
with open("report.pdf", "wb") as f:
    f.write(pdf_bytes)

---

Error Handling

Deliverable.generate_deliverable() raises NotFoundError when template_id doesn't match a template in the org, and ValidationError for invalid request parameters, most commonly a variable dict missing text (required unless it sets variableStack or isDisabled: True) or specifying an unsupported mimeType. Both extend the base TurboDocxError:

Handling Errors

import asyncio
from turbodocx_sdk import (
    Deliverable,
    TurboDocxError,
    AuthenticationError,
    AuthorizationError,
    ValidationError,
    NotFoundError,
    ConflictError,
    RateLimitError,
    NetworkError,
)

async def main():
    try:
        result = await Deliverable.generate_deliverable(
            name="Q1 Report",
            template_id="your-template-id",
            variables=[
                {"placeholder": "{CompanyName}", "text": "Acme Corp", "mimeType": "text"},
            ],
        )
    except AuthenticationError as e:
        print(f"Authentication failed: {e}")
        # Check your API key and org ID
    except AuthorizationError as e:
        print(f"Not authorized: {e}")
        # Authenticated, but lacks permission for this operation
    except ValidationError as e:
        print(f"Validation error: {e}")
        # Check request parameters
    except NotFoundError as e:
        print(f"Resource not found: {e}")
        # Template or deliverable doesn't exist
    except ConflictError as e:
        print(f"Conflict: {e}")
        # Request conflicts with the current resource state
    except RateLimitError as e:
        print(f"Rate limited: {e}")
        # Wait and retry
    except NetworkError as e:
        print(f"Network error: {e}")
        # Check connectivity
    except TurboDocxError as e:
        print(f"SDK error: {e}, status_code={e.status_code}, code={e.code}")

asyncio.run(main())

The full typed-error table (AuthenticationError, AuthorizationError, ConflictError, RateLimitError, NetworkError, HTTP status mapping) and the message/status_code/code attributes shared by every error are documented once in the Python SDK's Error Handling reference.

---

Python Types

The SDK uses Python type hints with Dict[str, Any] for flexible JSON-like structures.

Importing Types

from typing import Dict, List, Any, Optional

DeliverableVariable

Variable configuration for template injection:

 

Property	Type	Required	Description
placeholder	str	Yes	Template placeholder (e.g., {CompanyName})
text	str	No*	Value to inject
mimeType	str	Yes	"text", "html", "image", or "markdown"
isDisabled	bool	No	Skip this variable during generation
subvariables	list[dict]	No	Nested sub-variables for HTML content
variableStack	dict | list	No	Multiple instances for repeating content
aiPrompt	str	No	AI prompt for content generation (max 16,000 chars)

*Required unless variableStack is provided or isDisabled is true.

CreateDeliverableRequest

Request configuration for generate_deliverable:

 

Property	Type	Required	Description
name	str	Yes	Deliverable name (3-255 characters)
template_id	str	Yes	Template ID to generate from
variables	list[dict]	Yes	Variables for template substitution
description	str	No	Description (up to 65,535 characters)
tags	list[str]	No	Tag strings to associate

UpdateDeliverableRequest

Request configuration for update_deliverable_info:

 

Property	Type	Required	Description
name	str	No	Updated name (3-255 characters)
description	str	No	Updated description
tags	list[str]	No	Replace all tags (empty list to remove)

ListDeliverablesOptions

Options for list_deliverables:

 

Property	Type	Required	Description
limit	int	No	Results per page (1-100, default 6)
offset	int	No	Results to skip (default 0)
query	str	No	Search query to filter by name
show_tags	bool	No	Include tags in the response

DeliverableRecord

The deliverable object returned by list_deliverables:

 

Property	Type	Description
id	str	Unique deliverable ID (UUID)
name	str	Deliverable name
description	str	Description text
templateId	str	Source template ID
createdBy	str	User ID of the creator
email	str	Creator's email address
fileSize	int	File size in bytes
fileType	str	MIME type of the generated file
defaultFont	str	Default font used
fonts	list	Fonts used in the document
isActive	bool	Whether the deliverable is active
createdOn	str	ISO 8601 creation timestamp
updatedOn	str	ISO 8601 last update timestamp
tags	list	Associated tags (when show_tags=True)

DeliverableDetailRecord

The deliverable object returned by get_deliverable_details. Includes all fields from DeliverableRecord except fileSize, plus:

 

Property	Type	Description
templateName	str	Source template name
templateNotDeleted	bool	Whether the source template still exists
variables	list[dict]	Parsed variable objects with values

Tag

Tag object included when show_tags is enabled. Each tag is a dict with:

Key	Type	Description
id	str	Tag unique identifier (UUID)
label	str	Tag display name
isActive	bool	Whether the tag is active
updatedOn	str	ISO 8601 last update timestamp
createdOn	str	ISO 8601 creation timestamp
createdBy	str	User ID of the tag creator
orgId	str	Organization ID

---

Additional Documentation

For detailed information about advanced configuration and API concepts, see:

Core API References

• TurboDocx Templating - How to create and configure document templates
• Variable Reference - Complete guide to variable types, formatting, and advanced injection options
• API Reference - Full REST API documentation for Deliverable endpoints

---

Resources

• GitHub Repository
• PyPI Package
• API Reference