Skip to main content

Deliverable Ruby 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.

Skill countView on GitHubFull install guide →
bash — turbodocx
$npx skills add TurboDocx/quickstart
# then, inside your agent:›/turbodocx-sdk deliverable

The official TurboDocx Deliverable SDK for Ruby applications. Generate documents from templates with dynamic variable injection, download source files and PDFs, and manage deliverables programmatically with a simple synchronous API and comprehensive error handling. Available on RubyGems as turbodocx-sdk.

Installation​

gem install turbodocx-sdk

Requirements​

  • Ruby 2.7+
  • No runtime dependencies (uses the standard library's net/http)

Configuration​

require "turbodocx_sdk"

# Configure globally (recommended)
TurboDocxSdk::Deliverable.configure(
  api_key: ENV["TURBODOCX_API_KEY"],  # Required: Your TurboDocx API key
  org_id:  ENV["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​

require "turbodocx_sdk"

TurboDocxSdk::Deliverable.configure(
  api_key: ENV["TURBODOCX_API_KEY"],
  org_id:  ENV["TURBODOCX_ORG_ID"]
)

# Generate a document from a template with variables
# Request-hash keys are camelCase — the SDK forwards them to the API verbatim
result = TurboDocxSdk::Deliverable.generate_deliverable(
  "name"       => "Q1 Report",
  "templateId" => "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"]
)

puts JSON.pretty_generate(result)

Download and manage deliverables​

require "turbodocx_sdk"

TurboDocxSdk::Deliverable.configure(
  api_key: ENV["TURBODOCX_API_KEY"],
  org_id:  ENV["TURBODOCX_ORG_ID"]
)

# List deliverables with pagination
items = TurboDocxSdk::Deliverable.list_deliverables(limit: 10, show_tags: true)
puts "Total: #{items['totalRecords']}"

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

# Download source file (DOCX/PPTX)
source_bytes = TurboDocxSdk::Deliverable.download_source_file("deliverable-uuid")
File.binwrite("report.docx", source_bytes)

# Download PDF
pdf_bytes = TurboDocxSdk::Deliverable.download_pdf("deliverable-uuid")
File.binwrite("report.pdf", pdf_bytes)

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

# Delete deliverable
TurboDocxSdk::Deliverable.delete_deliverable("deliverable-uuid")

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​

Runnable snippets

The snippets below assume you have already called TurboDocxSdk::Deliverable.configure(...) and added require "turbodocx_sdk" (plus require "json" if the snippet calls JSON.pretty_generate), as shown in Quick Start. All methods are synchronous.

Configure​

Configure the SDK with your API credentials and organization settings.

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

All keyword arguments are optional and fall back to environment variables. 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 = TurboDocxSdk::Deliverable.generate_deliverable(
  "name"       => "Q1 Report",
  "templateId" => "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"]
)

puts JSON.pretty_generate(result)

List deliverables​

List deliverables with pagination, search, and filtering.

items = TurboDocxSdk::Deliverable.list_deliverables(
  limit:     10,
  offset:    0,
  query:     "report",
  show_tags: true
)

puts JSON.pretty_generate(items)

Get deliverable details​

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

details = TurboDocxSdk::Deliverable.get_deliverable_details("deliverable-uuid", show_tags: true)

puts JSON.pretty_generate(details)

Update deliverable info​

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

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

puts JSON.pretty_generate(result)

Delete deliverable​

Soft-delete a deliverable.

result = TurboDocxSdk::Deliverable.delete_deliverable("deliverable-uuid")

puts JSON.pretty_generate(result)

Download source file​

Download the original source file (DOCX or PPTX).

source_bytes = TurboDocxSdk::Deliverable.download_source_file("deliverable-uuid")

# Save to file
File.binwrite("report.docx", source_bytes)

Download PDF​

Download the PDF version of a deliverable.

pdf_bytes = TurboDocxSdk::Deliverable.download_pdf("deliverable-uuid")

# Save to file
File.binwrite("report.pdf", pdf_bytes)

Error Handling​

The SDK provides typed error classes for different failure scenarios. All errors extend the base TurboDocxSdk::TurboDocxError class.

Error Classes​

Error ClassStatus CodeDescription
TurboDocxErrorvariesBase error class for all SDK errors
AuthenticationError401Invalid or missing API credentials
AuthorizationError403Authenticated but lacks required permissions
ValidationError400Invalid request parameters
NotFoundError404Deliverable or template not found
ConflictError409Request conflicts with current resource state
RateLimitError429Too many requests
NetworkError-Network connectivity issues

Handling Errors​

require "turbodocx_sdk"

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

Error Properties​

All errors include these properties:

PropertyTypeDescription
messageStringHuman-readable error description
status_codeInteger | nilHTTP status code (if applicable)
codeString | nilMachine-readable error code

Ruby Request Hashes​

The SDK uses plain Ruby Hash objects for flexible JSON-like structures. Request-body keys stay camelCase (the SDK forwards them verbatim); only the method keyword arguments (api_key:, show_tags:, …) are snake_case.

DeliverableVariable​

Variable configuration for template injection:

 

PropertyTypeRequiredDescription
placeholderStringYesTemplate placeholder (e.g., {CompanyName})
textStringNo*Value to inject
mimeTypeStringYes"text", "html", "image", or "markdown"
isDisabledBooleanNoSkip this variable during generation
subvariablesArray<Hash>NoNested sub-variables for HTML content
variableStackHash | ArrayNoMultiple instances for repeating content
aiPromptStringNoAI prompt for content generation (max 16,000 chars)

*Required unless variableStack is provided or isDisabled is true.

CreateDeliverableRequest​

Request hash for generate_deliverable:

 

PropertyTypeRequiredDescription
nameStringYesDeliverable name (3-255 characters)
templateIdStringYesTemplate ID to generate from
variablesArray<Hash>YesVariables for template substitution
descriptionStringNoDescription (up to 65,535 characters)
tagsArray<String>NoTag strings to associate

UpdateDeliverableRequest​

Request hash for update_deliverable_info:

 

PropertyTypeRequiredDescription
nameStringNoUpdated name (3-255 characters)
descriptionStringNoUpdated description
tagsArray<String>NoReplace all tags (empty array to remove)

ListDeliverablesOptions​

Options hash for list_deliverables (these are query parameters — show_tags is accepted as snake_case or camelCase and sent as showTags):

 

PropertyTypeRequiredDescription
limitIntegerNoResults per page (1-100, default 6)
offsetIntegerNoResults to skip (default 0)
queryStringNoSearch query to filter by name
show_tagsBooleanNoInclude tags in the response

DeliverableRecord​

The deliverable hash returned by list_deliverables:

 

PropertyTypeDescription
idStringUnique deliverable ID (UUID)
nameStringDeliverable name
descriptionStringDescription text
templateIdStringSource template ID
createdByStringUser ID of the creator
emailStringCreator's email address
fileSizeIntegerFile size in bytes
fileTypeStringMIME type of the generated file
defaultFontStringDefault font used
fontsArrayFonts used in the document
isActiveBooleanWhether the deliverable is active
createdOnStringISO 8601 creation timestamp
updatedOnStringISO 8601 last update timestamp
tagsArrayAssociated tags (when show_tags: true)

DeliverableDetailRecord​

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

 

PropertyTypeDescription
templateNameStringSource template name
templateNotDeletedBooleanWhether the source template still exists
variablesArray<Hash>Parsed variable objects with values

Tag​

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

KeyTypeDescription
idStringTag unique identifier (UUID)
labelStringTag display name
isActiveBooleanWhether the tag is active
updatedOnStringISO 8601 last update timestamp
createdOnStringISO 8601 creation timestamp
createdByStringUser ID of the tag creator
orgIdStringOrganization ID

Additional Documentation​

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

Core API References​

Resources​

Last updated on