API Reference

Integrate ComposeIt document generation and template management into your workflows.

Generate PDF, HTML, and image files programmatically by sending JSON data payloads to your activated templates using the ComposeIt REST API.

Authentication

All API requests must include your API key in the custom header:

Header Name	Description
`x-api-key`	Your private organization API key. Manage these in Dashboard > API Keys.

API Keys

Treat your API keys as passwords. Do not expose them in client-side code (e.g. browsers, mobile applications) or public source control repositories.

API Key Permissions

API keys can be scoped with granular access permissions. Ensure that your key possesses the permissions required by the endpoints you call:

Permission	Description	Endpoints
`templates:read`	Read templates, metadata, and version history.	`GET /api/templates`, `GET /api/templates/:templateId`, `GET /api/templates/:templateId/versions`, `GET /api/templates/:templateId/:versionId`
`templates:write`	Modify template metadata.	`PATCH /api/templates/:templateId`
`documents:read`	List and retrieve compiled documents.	`GET /api/documents`, `GET /api/documents/:documentId`
`documents:write`	Render and export documents from templates.	`POST /api/export`

Templates

List Templates

Retrieve a paginated list of templates belonging to your organization.

Endpoint: GET /api/templates
Required Permission: templates:read

Query Parameters

Parameter	Type	Required	Description
`page`	Number	No	1-based page number (used when `pageSize` is provided).
`pageSize`	Number	No	Number of records per page (between 1 and 100).
`q`	String	No	Search query to filter templates by name.
`recentlyUpdated`	Boolean	No	Pass `true` to sort by `updatedAt` descending (defaults to sorting by `createdAt` descending).

Request Example

curl -X GET "https://app.composeit.app/api/templates?page=1&pageSize=10&q=invoice" \
  -H "x-api-key: your_live_api_key_here"

Response Format

{
  "data": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "organizationId": "org_123456789",
      "folderId": null,
      "name": "Standard Invoice",
      "description": "Invoice template for customer billing",
      "dataSource": null,
      "templateType": "document",
      "thumbnailUrl": "https://storage.composeit.website/thumbnails/tmpl_1.png",
      "isActive": true,
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-22T14:30:00.000Z",
      "createdBy": {
        "id": "user_123456789",
        "name": "Alex Smith",
        "email": "alex@example.com",
        "image": null
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1
  }
}

Get Template

Retrieve the full details and definition of a specific template.

Endpoint: GET /api/templates/:templateId
Required Permission: templates:read

Path Parameters

Parameter	Type	Required	Description
`templateId`	String	Yes	The unique identifier (UUID) of the template.

Query Parameters

Parameter	Type	Required	Description
`typeOnly`	Boolean	No	If `true`, returns only `{ id, templateType }`. Defaults to `false`.

Request Example

curl -X GET https://app.composeit.app/api/templates/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "x-api-key: your_live_api_key_here"

Response Format

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "organizationId": "org_123456789",
  "createdById": "user_123456789",
  "trashedById": null,
  "folderId": null,
  "name": "Standard Invoice",
  "description": "Invoice template for customer billing",
  "thumbnailUrl": "https://storage.composeit.website/thumbnails/tmpl_1.png",
  "definition": {
    "schema": [],
    "components": []
  },
  "templateType": "document",
  "dataSource": null,
  "isActive": true,
  "isFavorite": false,
  "isTrashed": false,
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-09-22T14:30:00.000Z",
  "trashedAt": null,
  "version": 1
}

Update Template

Update metadata and settings for an existing template.

Endpoint: PATCH /api/templates/:templateId
Content-Type: application/json
Required Permission: templates:write

Path Parameters

Parameter	Type	Required	Description
`templateId`	String	Yes	The unique identifier (UUID) of the template to update.

Request Parameters

Field	Type	Required	Description
`name`	String	No	Updated template display name.
`description`	String / null	No	Updated description for the template.
`folderId`	String / null	No	Target folder UUID to place the template in, or `null`.
`isActive`	Boolean	No	Whether the template is active and available for rendering.
`isFavorite`	Boolean	No	Whether the template is marked as a favorite.
`createVersion`	Boolean	No	When `true`, increments the template's version counter.

Modifying the visual definition directly via API keys is omitted to avoid unintentional template corruption. Visual definitions should be modified through the ComposeIt Editor.

Request Example

curl -X PATCH https://app.composeit.app/api/templates/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_live_api_key_here" \
  -d '{
    "name": "Standard Invoice - Updated",
    "description": "Updated invoice template for enterprise customers",
    "isActive": true
  }'

Response Format

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "organizationId": "org_123456789",
  "createdById": "user_123456789",
  "trashedById": null,
  "folderId": null,
  "name": "Standard Invoice - Updated",
  "description": "Updated invoice template for enterprise customers",
  "thumbnailUrl": "https://storage.composeit.website/thumbnails/tmpl_1.png",
  "templateType": "document",
  "dataSource": null,
  "isActive": true,
  "isFavorite": false,
  "isTrashed": false,
  "createdAt": "2026-09-01T10:00:00.000Z",
  "updatedAt": "2026-09-22T15:00:00.000Z",
  "trashedAt": null,
  "version": 1
}

List Template Versions

Retrieve the version history and snapshots for a given template.

Endpoint: GET /api/templates/:templateId/versions
Required Permission: templates:read

Path Parameters

Parameter	Type	Required	Description
`templateId`	String	Yes	The unique identifier (UUID) of the template.

Request Example

curl -X GET https://app.composeit.app/api/templates/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/versions \
  -H "x-api-key: your_live_api_key_here"

Response Format

[
  {
    "id": "ver_f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "description": "Initial Version",
    "version": 1,
    "createdAt": "2026-09-01T10:00:00.000Z",
    "createdBy": {
      "id": "user_123456789",
      "name": "Alex Smith",
      "email": "alex@example.com",
      "image": null
    }
  }
]

Get Template Version

Retrieve a specific version snapshot of a template, including its definition.

Endpoint: GET /api/templates/:templateId/:versionId
Required Permission: templates:read

Path Parameters

Parameter	Type	Required	Description
`templateId`	String	Yes	The unique identifier (UUID) of the template.
`versionId`	String	Yes	The unique identifier (UUID) of the version record.

Request Example

curl -X GET https://app.composeit.app/api/templates/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/ver_f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "x-api-key: your_live_api_key_here"

Response Format

{
  "id": "ver_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "description": "Initial Version",
  "version": 1,
  "definition": {
    "schema": [],
    "components": []
  },
  "createdById": "user_123456789",
  "createdAt": "2026-09-01T10:00:00.000Z"
}

Documents

Render Document

Generate compiled documents by compiling a template definition with dynamic data.

Endpoint: POST /api/export
Content-Type: application/json
Required Permission: documents:write

Request Parameters

Field	Type	Required	Description
`templateId`	String	Yes	The UUID of the template you wish to render.
`templateVersion`	Number	No	A specific version number to render. Defaults to the active template version.
`formats`	Array	Yes	Output formats to compile. Allowed values: `["pdf", "html", "image", "mjml"]`.
`data`	Object	No	Key-value pairs containing variables referenced inside your template.
`expiresAt`	String	No	ISO 8601 timestamp or Date indicating when generated download links expire. (Default: 24 hours).
`imageType`	String	No	Output format of compiled images: `"png"` or `"jpg"`. (Default: `"png"`).
`isTest`	Boolean	No	If `true`, compiles document with a watermark without counting against usage limits.
`sendForSignature`	Boolean	No	Set to `true` to initiate a DocuSeal e-signature request using the compiled PDF.
`docusealConnection`	String	No	Specific DocuSeal Connection ID to use for the signature request. Use this if you are using the visual settings and field mapping.
`docusealSettings`	Object	No	Configuration object for DocuSeal submitters, expiration, and messages (see below).

`docusealSettings` Schema

Field	Type	Description
`submitters`	Array	Array of recipient/signer objects to receive the document for signing.
`expiresAt`	String / Date	Expiration timestamp for the e-signature request.
`message`	Object	Custom email details sent to submitters/signers.

`docusealSettings.submitters` Object Schema

Field	Type	Required	Description
`role`	String	Yes	The role name assigned to the signer in the template (e.g., `"Client"`, `"First Party"`).
`email`	String	Yes	Email address of the recipient.
`name`	String	No	Full name of the recipient.
`values`	Object	No	Pre-filled field values for this specific submitter (key-value map).
`order`	Number	No	Signing order sequence number for sequential signatures (e.g., `1`, `2`).

`docusealSettings.message` Object Schema

Field	Type	Description
`subject`	String	Custom email subject line.
`body`	String	Custom body message/instructions for signers.

Request Example

curl -X POST https://app.composeit.app/api/export \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_live_api_key_here" \
  -d '{
    "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "formats": ["pdf", "html"],
    "isTest": false,
    "data": {
      "number": "INV-10024",
      "date": "2026-06-26",
      "due_data": "2026-07-26",
      "bill_to": {
        "name": "Acme Corporation",
        "address": "123 Industrial Parkway, Suite A"
      },
      "products": [
        {
          "name": "Premium Plan Subscription",
          "quantity": 1,
          "unit_price": 99.00,
          "total": 99.00
        },
        {
          "name": "Setup & Configuration Service",
          "quantity": 2,
          "unit_price": 50.00,
          "total": 100.00
        }
      ],
      "sub_total": 199.00,
      "tax": 19.90,
      "grand_total": 218.90,
      "notes": "Thank you for partnering with ComposeIt!"
    }
  }'

Request Example (Send for Signature)

curl -X POST https://app.composeit.app/api/export \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_live_api_key_here" \
  -d '{
    "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "formats": ["pdf"],
    "sendForSignature": true,
    "docusealConnection": "conn_123456789",
    "docusealSettings": {
      "submitters": [
        {
          "role": "Client",
          "email": "john.doe@example.com",
          "name": "John Doe",
          "order": 1,
          "values": {
            "company_name": "Acme Corp"
          }
        },
        {
          "role": "Approver",
          "email": "jane.smith@example.com",
          "name": "Jane Smith",
          "order": 2
        }
      ],
      "expiresAt": "2026-09-01T00:00:00.000Z",
      "message": {
        "subject": "Action Required: Sign Rental Agreement",
        "body": "Please review and sign the attached rental agreement document."
      }
    },
    "data": {
      "agreement_date": "2026-08-20",
      "monthly_rent": 1200
    }
  }'

Response Format

{
  "pdf": {
    "url": "https://storage.composeit.website/outputs/9b1deb4d-pdf-output.pdf",
    "sizeBytes": 204550,
    "mimeType": "application/pdf",
    "checksum": "d3b07384d113edec49eaa6238ad5ff00"
  },
  "html": {
    "htmlDocument": "<!DOCTYPE html><html><head><style>...</style></head><body>...</body></html>",
    "checksum": "3b07384d113edec49eaa6238ad5ff001",
    "mimeType": "text/html",
    "url": "",
    "sizeBytes": 14205
  }
}

List Documents

Retrieve a paginated list of generated documents for your organization.

Endpoint: GET /api/documents
Required Permission: documents:read

Query Parameters

Parameter	Type	Required	Description
`page`	Number	No	1-based page number (used when `pageSize` is provided).
`pageSize`	Number	No	Number of records per page (between 1 and 100).

Request Example

curl -X GET "https://app.composeit.app/api/documents?page=1&pageSize=10" \
  -H "x-api-key: your_live_api_key_here"

Response Format

{
  "data": [
    {
      "id": "doc_e7a2b901-4c5f-4f81-8b5e-2f9602bc6e34",
      "organizationId": "org_123456789",
      "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "createdById": "user_123456789",
      "status": "succeeded",
      "outputs": [
        {
          "label": "Document PDF",
          "storageKey": "exports/doc_e7a2b901.pdf",
          "url": "https://storage.composeit.website/outputs/doc_e7a2b901.pdf",
          "mimeType": "application/pdf",
          "sizeBytes": 204550,
          "checksum": "d3b07384d113edec49eaa6238ad5ff00"
        }
      ],
      "metadata": null,
      "expiresAt": "2026-09-23T12:00:00.000Z",
      "createdAt": "2026-09-22T12:00:00.000Z",
      "updatedAt": "2026-09-22T12:00:00.000Z",
      "createdBy": {
        "id": "user_123456789",
        "name": "Alex Smith",
        "email": "alex@example.com",
        "image": null
      },
      "template": {
        "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "name": "Standard Invoice"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1
  }
}

Get Document

Retrieve the metadata and generated output files for a single document.

Endpoint: GET /api/documents/:documentId
Required Permission: documents:read

Path Parameters

Parameter	Type	Required	Description
`documentId`	String	Yes	The unique identifier (UUID) of the document.

Request Example

curl -X GET https://app.composeit.app/api/documents/doc_e7a2b901-4c5f-4f81-8b5e-2f9602bc6e34 \
  -H "x-api-key: your_live_api_key_here"

Response Format

{
  "id": "doc_e7a2b901-4c5f-4f81-8b5e-2f9602bc6e34",
  "organizationId": "org_123456789",
  "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "createdById": "user_123456789",
  "status": "succeeded",
  "outputs": [
    {
      "label": "Document PDF",
      "storageKey": "exports/doc_e7a2b901.pdf",
      "url": "https://storage.composeit.website/outputs/doc_e7a2b901.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 204550,
      "checksum": "d3b07384d113edec49eaa6238ad5ff00"
    }
  ],
  "metadata": null,
  "expiresAt": "2026-09-23T12:00:00.000Z",
  "createdAt": "2026-09-22T12:00:00.000Z",
  "updatedAt": "2026-09-22T12:00:00.000Z"
}

Batch Document Generation

Execute asynchronous, high-volume document rendering jobs across multiple payloads or external records.

Premium Feature

Batch generation is available exclusively on Premium and Enterprise plans. Refer to the Batch Processing Guide for webhooks and queue lifecycle details.

Create Batch Job

Submit a batch of documents for rendering. All documents are created immediately with status: "queued" and returned in the response while background workers compile them.

Endpoint: POST /api/export/batch
Required Permission: documents:write
Status Code: 202 Accepted

Request Parameters

Parameter	Type	Required	Description
`templateId`	String	Yes	ID of the template to render.
`formats`	Array	Yes	Output formats (`["pdf"]`, `["html"]`, `["image"]`, `["mjml"]`).
`items`	Array	Yes	Array of items with dynamic `data` and custom `metadata`.
`templateVersion`	Number	No	Optional version snapshot number.
`expiresAt`	Date / String	No	Document expiration timestamp.

Request Example

curl -X POST "https://app.composeit.app/api/export/batch" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_live_api_key_here" \
  -d '{
    "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "formats": ["pdf"],
    "items": [
      { "data": { "invoiceNumber": "INV-101", "total": 450.00 } },
      { "data": { "invoiceNumber": "INV-102", "total": 890.00 } }
    ]
  }'

Response Format (`202 Accepted`)

{
  "batchId": "batch_88ab12cf9",
  "totalCount": 2,
  "status": "queued",
  "documents": [
    {
      "id": "doc_01a",
      "organizationId": "org_123",
      "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "status": "queued",
      "outputs": [],
      "createdAt": "2026-10-07T12:00:00.000Z"
    },
    {
      "id": "doc_02b",
      "organizationId": "org_123",
      "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "status": "queued",
      "outputs": [],
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ]
}

Platform Batch Job

Batch render documents directly from external integrations (Airtable, Notion, etc.) for a list of record IDs.

Endpoint: POST /api/export/batch/:platform
Required Permission: documents:write
Status Code: 202 Accepted

curl -X POST "https://app.composeit.app/api/export/batch/airtable" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_live_api_key_here" \
  -d '{
    "templateId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "recordIds": ["rec_123", "rec_456"]
  }'

Error Handling

API responses return appropriate HTTP status codes along with a JSON error payload:

400 Bad Request: Missing headers, invalid payload, or insufficient API key permissions.
401 Unauthorized: Missing, revoked, or invalid x-api-key.
404 Not Found: The requested template, version, or document does not exist.
500 Internal Server Error: An unexpected server error occurred during processing.

Example Error Payload

{
  "error": "Unauthorized"
}

API Reference

On this page