<a id="generating-document-templates-via-the-api"></a>
<a id="api-document-templates"></a>
# Generating Document Templates via the API

TrialGrid supports user-defined [document templates](../urls/document_templates/index.html.md#document-templates) that produce Word, Excel, PDF or text reports for a Draft or a Project. The same generation flow is available over the REST API: callers can list the templates available for a Draft or Project, kick off a generation, poll the resulting background task, and download the finished file from a pre-signed AWS S3 URL.

This page walks through the end-to-end flow with two worked examples — one in Python, one in Node.js — using a fictional Excel template called **Project Form Inventory**.

<a id="behaviour-and-constraints"></a>
## Behaviour and constraints

- **API requests run as you.** Generating a document via the API is identical to clicking *Generate* in the UI: the document is created in **your** user scope, with **your** permissions, and the resulting file is added to [your Documents collection](../user_documents.html.md#user-documents) on the homepage. Anything you can run from the UI you can run from the API; anything you cannot run from the UI you cannot run from the API.
- **Generation is asynchronous.** The generate endpoint enqueues a background task and returns immediately with a `task_id`. You poll the task's status endpoint until it reports completion (or failure).
- **Downloads come straight from AWS S3.** When the task is complete the status response includes a download URL. This URL is a **pre-signed S3 URL** — the file is served directly from S3 and never proxied through TrialGrid's own servers. The URL is **time-limited**: it expires after a short period (typically one hour).
- **The file persists; the URL does not.** If your download URL has expired but you still want the same file, simply call the status endpoint again — it will return a freshly-signed URL pointing at the same stored result. The file itself is preserved in your [Documents collection](../user_documents.html.md#user-documents) until you delete it.
- **Project Tickets templates are not available via the API.** Document templates with a scope of *Project Tickets* cannot currently be generated through this API. Use the TrialGrid UI to run those.
- **The generate endpoint is rate-limited.** Each generation kicks off a background task and writes a file to storage, so the `POST /document_templates/<id>/generate/` endpoint is capped at **60 requests per hour per user** by default (in addition to the global API rate limit that applies to every endpoint). When the cap is reached the API returns `429 Too Many Requests` with a `Retry-After` header indicating how long to wait before retrying. The list, status and download endpoints are not subject to this tighter cap.

<a id="authentication"></a>
## Authentication

Document template endpoints accept the same credentials as the rest of the TrialGrid API — see [Authentication](authentication.html.md#api-authentication) for full details. The two schemes are:

**HTTP Basic Authentication** — send your TrialGrid username and password in the standard `Authorization` header. The server expects a base64-encoded `username:password` value:

```
Authorization: Basic YWxpY2VAZXhhbXBsZS5jb206c2VjcmV0LXBhc3N3b3Jk
```

**Token Authentication** — obtain a token from the [token endpoint](/api/v1/documentation) (see [Token Authentication](authentication.html.md#api-token-authentication) for how to generate and revoke tokens) and send it in the `Authorization` header prefixed with `Token`:

```
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b
```

Either scheme works against every endpoint described on this page. The worked examples below show how to set both header styles in code.

> **Important:** Do **not** send TrialGrid credentials when issuing the final `GET` against the signed S3 download URL — the signature embedded in the URL is what authorises that request, and adding an unrelated `Authorization` header can cause the download to fail.

<a id="setting-the-scene-our-worked-example"></a>
## Setting the scene — our worked example

Imagine your administrator has already created the following Excel-type template in TrialGrid:

- **Attribute:** Name

  **Value:** Project Form Inventory

- **Attribute:** Type

  **Value:** Excel 2003/2004 SpreadsheetML with conversion to XLSX

- **Attribute:** Scope

  **Value:** Project Home

- **Attribute:** Settings

  **Value:**

  - `include_inactive_forms` (boolean, default `false`) — include forms marked inactive
  - `sort_by` (choice: `FormName` or `OID`, default `FormName`) — how to sort the form list
  - `report_title` (text, default `Form Inventory`) — heading shown at the top of the spreadsheet

Across the worked examples below we will:

1. Discover the template's `id` and the names of its settings.
2. Submit a generation request for a specific Project, overriding `include_inactive_forms` to `true` and `sort_by` to `OID`.
3. Poll the resulting background task until it completes.
4. Download the finished `.xlsx` file from S3.

<a id="endpoint-summary"></a>
## Endpoint summary

Every endpoint below is versioned with `v1` or `v2`; the examples use `v2` but there is no difference.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/v2/drafts/{draft_id}/document_templates/` | List `Draft Home`-scoped templates available for that draft |
| `GET` | `/api/v2/projects/{project_id}/document_templates/` | List `Project Home`-scoped templates available for that project |
| `POST` | `/api/v2/document_templates/{annotate_def_id}/generate/` | Start a background generation, returns a `task_id` |
| `GET` | `/api/v2/document_template_tasks/{task_id}/` | Poll task status; when complete includes a signed S3 download URL |

<a id="discover-the-template"></a>
## 1. Discover the template

Before you can generate anything you need the template's `id` and the exact names of its settings. List the templates available for the Project (or Draft) you intend to report on:

```
GET /api/v2/projects/123/document_templates/
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b
```

(or, equivalently, `Authorization: Basic <base64-encoded username:password>` — see the [Authentication](#authentication) section above.)

Response:

```json
{
    "results": [
        {
            "id": 42,
            "name": "Project Form Inventory",
            "description": "All forms across all drafts in this project.",
            "template_type": "Excel 2003/2004 SpreadsheetML with conversion to XLSX",
            "template_scope": "Project Home",
            "settings": [
                {
                    "name": "include_inactive_forms",
                    "display_name": "Include inactive forms?",
                    "description": "When checked, inactive forms are included in the output.",
                    "setting_type": "boolean",
                    "default_value": "false",
                    "setting_choices": null,
                    "display_order": 0
                },
                {
                    "name": "sort_by",
                    "display_name": "Sort forms by",
                    "description": "Order the form rows in the spreadsheet.",
                    "setting_type": "choice",
                    "default_value": "FormName",
                    "setting_choices": ["FormName", "OID"],
                    "display_order": 1
                },
                {
                    "name": "report_title",
                    "display_name": "Report title",
                    "description": "Heading shown at the top of the spreadsheet.",
                    "setting_type": "text",
                    "default_value": "Form Inventory",
                    "setting_choices": null,
                    "display_order": 2
                }
            ]
        }
    ]
}
```

The discovery endpoint only lists templates that are **active** and that match the requested scope. Templates outside your URL are excluded.

> **Note:** `template_type` and `template_scope` are returned as the system's stored display strings (e.g. `"Excel 2003/2004 SpreadsheetML with conversion to XLSX"`). Treat them as opaque labels — match them by equality, don't parse them — they may be reworded between releases.

<a id="start-a-generation"></a>
## 2. Start a generation

POST to the generate endpoint, supplying the scope-specific id (`project_id` for a Project Home template, `draft_id` for a Draft Home template) and a `settings` object whose keys match the setting names from the discovery response. Any setting you omit falls back to its default.

Each value must be sent as the JSON type its `setting_type` calls for:

| `setting_type` | Value |
| --- | --- |
| `boolean` | `true` or `false` |
| `text` | A string |
| `choice` | One of the `setting_choices` strings |
| `draft` | The integer id of a Draft in the Project the document is generated in (for a Draft Home template, that Draft's Project), or `null` for none. When the setting's `multiple` is `true`, a list of integer Draft ids from that Project, which may be empty |

A Draft id from any other Project, or of a deleted Draft, is rejected with HTTP 400.

A setting whose `required` is `true` in the discovery response must end up with a value. A `text` value that is empty or only spaces, or a `draft` value of `null` or an empty list, is rejected with HTTP 400 naming the setting by its display name. An omitted setting takes its default first, so a required setting with a default is satisfied by leaving it out.

```
POST /api/v2/document_templates/42/generate/
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b
Content-Type: application/json

{
    "project_id": 123,
    "settings": {
        "include_inactive_forms": true,
        "sort_by": "OID",
        "report_title": "Q2 form audit"
    }
}
```

Response (HTTP 202 Accepted):

```json
{
    "task_id": 9876,
    "status_url": "/api/v2/document_template_tasks/9876/"
}
```

<a id="poll-the-task"></a>
## 3. Poll the task

The generation runs as a background task. Poll the `status_url` until `state` is `C` (complete) or `F` (failed):

```
GET /api/v2/document_template_tasks/9876/
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b
```

While the task is still running the response will look like (`download` is `null` until the task finishes successfully):

```json
{
    "task_id": 9876,
    "name": "Generate Annotate",
    "task_type": "generate_annotate",
    "state": "R",
    "state_display": "Running",
    "progress_pct": 40,
    "state_message": "Generating Excel rows...",
    "created": "2026-05-06T10:00:00+00:00",
    "updated": "2026-05-06T10:00:08+00:00",
    "download": null
}
```

Once the task completes successfully the `download` block is populated:

```json
{
    "task_id": 9876,
    "name": "Generate Annotate",
    "task_type": "generate_annotate",
    "state": "C",
    "state_display": "Complete",
    "progress_pct": 100,
    "state_message": "Generation complete",
    "created": "2026-05-06T10:00:00+00:00",
    "updated": "2026-05-06T10:00:23+00:00",
    "download": {
        "url": "https://s3.amazonaws.com/.../annotate.xlsx?X-Amz-Signature=...",
        "filename": "Project Form Inventory.xlsx",
        "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "size_in_bytes": 18234,
        "expires_in_seconds": 3600
    }
}
```

State codes are: `P` Pending, `R` Running, `C` Complete, `F` Failed, `X` Cancelled.

A reasonable poll cadence is every 2 – 5 seconds; large reports can take several minutes to generate. Note that progress_pct value may not change smoothly on each poll request, do not assume the task has stalled because this value has not changed between poll requests.

<a id="download-the-result"></a>
## 4. Download the result

The `download.url` is a **pre-signed AWS S3 URL**. Issue an HTTP `GET` to it (no TrialGrid auth header required — the signature in the URL is what authorises the download) and stream the body to disk. The S3 response sets the correct `Content-Type` and `Content-Disposition: attachment` headers based on the template type.

The URL is valid for `download.expires_in_seconds` seconds (typically 3600). If it expires before you finish, simply call the status endpoint again — every call generates a fresh signed URL pointing at the same stored file. The file itself remains in your [Documents collection](../user_documents.html.md#user-documents) until you delete it.

<a id="worked-example-python"></a>
## Worked example — Python

This example uses `requests`. Install with `pip install requests`. Edit the constants at the top for your environment, or set the matching `EXAMPLE_*` environment variables.

```python
# Copyright TrialGrid Limited

"""End-to-end example of generating a document template through the TrialGrid API.

This script:

1. Looks up a Project Home document template by name.
2. Submits a generation request, overriding three of its settings.
3. Polls the resulting background task until completion (or failure).
4. Downloads the finished file straight from the pre-signed S3 URL.

Edit the ``Configuration`` constants below for your environment, or set the matching
``EXAMPLE_*`` environment variables (the test suite uses the env-var path).
"""

import base64
import os
import time
from pathlib import Path

import requests

# ---- Configuration ----------------------------------------------------------------------
# Edit these constants for your environment, or set the matching environment variables.

BASE_URL = os.environ.get("EXAMPLE_BASE_URL", "https://www.trialgrid.io/api/v2")
PROJECT_ID = int(os.environ.get("EXAMPLE_PROJECT_ID", "123"))
TEMPLATE_NAME = os.environ.get("EXAMPLE_TEMPLATE_NAME", "Project Form Inventory")
OUTPUT_DIR = Path(os.environ.get("EXAMPLE_OUTPUT_DIR", ""))

# ---- Authentication: pick ONE of the two styles below -----------------------------------
# (a) HTTP Basic Authentication - username + password.
USERNAME = os.environ.get("EXAMPLE_USERNAME", "alice@example.com")
PASSWORD = os.environ.get("EXAMPLE_PASSWORD", "<your password>")
AUTH_HEADERS = {
    "Authorization": "Basic " + base64.b64encode(f"{USERNAME}:{PASSWORD}".encode()).decode(),
}
# (b) Token Authentication - see https://www.trialgrid.io/docs/api.html#token-authentication
#     for how to generate or revoke tokens.
# AUTH_HEADERS = {"Authorization": "Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b"}
# -----------------------------------------------------------------------------------------

POLL_SECONDS = float(os.environ.get("EXAMPLE_POLL_SECONDS", "3"))
TIMEOUT_SECONDS = int(os.environ.get("EXAMPLE_TIMEOUT_SECONDS", "600"))

def find_template(project_id: int, name: str) -> dict:
    """Look up a Project Home template by name and return its definition."""
    resp = requests.get(
        f"{BASE_URL}/projects/{project_id}/document_templates/",
        headers=AUTH_HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    for template in resp.json()["results"]:
        if template["name"] == name:
            return template
    raise LookupError(f"No template named {name!r} on project {project_id}")

def start_generation(template_id: int, project_id: int, settings: dict) -> int:
    """Kick off a generation. Returns the task_id."""
    resp = requests.post(
        f"{BASE_URL}/document_templates/{template_id}/generate/",
        json={"project_id": project_id, "settings": settings},
        headers=AUTH_HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]

def wait_for_completion(
    task_id: int, poll_seconds: float = POLL_SECONDS, timeout_seconds: int = TIMEOUT_SECONDS
) -> dict:
    """Poll until the task is Complete or Failed. Returns the final status payload."""
    deadline = time.monotonic() + timeout_seconds
    while True:
        resp = requests.get(
            f"{BASE_URL}/document_template_tasks/{task_id}/",
            headers=AUTH_HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        status = resp.json()
        state = status["state"]
        if state == "C":
            return status
        if state == "F":
            raise RuntimeError(f"Generation failed: {status['state_message']}")
        if time.monotonic() > deadline:
            raise TimeoutError(f"Task {task_id} did not complete in {timeout_seconds}s")
        print(f"  state={state} progress={status['progress_pct']}% - {status['state_message']}")
        time.sleep(poll_seconds)

def download(status: dict, save_to: Path) -> None:
    """Stream the file to disk from the signed S3 URL.

    The S3 URL is time-limited (see ``download.expires_in_seconds``). If it has expired,
    re-poll ``document_template_tasks/{task_id}/`` to get a fresh URL for the same file.
    """
    download_info = status["download"]
    # Note: do NOT send AUTH_HEADERS here - the signed URL authorises the request, and
    # adding an unrelated Authorization header can cause S3 to reject the download.
    with requests.get(download_info["url"], stream=True, timeout=60) as resp:
        resp.raise_for_status()
        with save_to.open("wb") as fh:
            for chunk in resp.iter_content(chunk_size=64 * 1024):
                fh.write(chunk)
    print(f"Saved {download_info['size_in_bytes']} bytes to {save_to}")

if __name__ == "__main__":
    template = find_template(PROJECT_ID, TEMPLATE_NAME)
    print(f"Found template id={template['id']} ({template['template_type']})")

    task_id = start_generation(
        template_id=template["id"],
        project_id=PROJECT_ID,
        settings={
            "include_inactive_forms": True,
            "sort_by": "OID",
            "report_title": "Q2 form audit",
        },
    )
    print(f"Started task {task_id}")

    final = wait_for_completion(task_id)
    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
    download(final, OUTPUT_DIR / final["download"]["filename"])
```

<a id="worked-example-node-js"></a>
## Worked example — Node.js

This example uses Node.js 18+ (which has `fetch` built in) and the standard library only.

```javascript
// Copyright TrialGrid Limited
//
// End-to-end example of generating a document template through the TrialGrid API.
//
// This script:
//  1. Looks up a Project Home document template by name.
//  2. Submits a generation request, overriding three of its settings.
//  3. Polls the resulting background task until completion (or failure).
//  4. Downloads the finished file straight from the pre-signed S3 URL.
//
// Edit the Configuration constants below for your environment, or set the matching
// EXAMPLE_* environment variables (the test suite uses the env-var path).
//
// Requires Node.js 18+ for built-in fetch.

import { writeFile, mkdir } from "node:fs/promises";
import { Buffer } from "node:buffer";
import { join } from "node:path";

// ---- Configuration ----------------------------------------------------------------------
// Edit these constants for your environment, or set the matching environment variables.

const BASE_URL = process.env.EXAMPLE_BASE_URL ?? "https://www.trialgrid.io/api/v2";
const PROJECT_ID = parseInt(process.env.EXAMPLE_PROJECT_ID ?? "123", 10);
const TEMPLATE_NAME = process.env.EXAMPLE_TEMPLATE_NAME ?? "Project Form Inventory";
const OUTPUT_DIR = process.env.EXAMPLE_OUTPUT_DIR ?? ".";

// ---- Authentication: pick ONE of the two styles below -----------------------------------
// (a) HTTP Basic Authentication — username + password.
const USERNAME = process.env.EXAMPLE_USERNAME ?? "alice@example.com";
const PASSWORD = process.env.EXAMPLE_PASSWORD ?? "<your password>";
const AUTH_HEADERS = {
    Authorization: "Basic " + Buffer.from(`${USERNAME}:${PASSWORD}`).toString("base64"),
};
// (b) Token Authentication — see https://www.trialgrid.io/docs/api.html#token-authentication
//     for how to generate or revoke tokens.
// const AUTH_HEADERS = { Authorization: "Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b" };
// -----------------------------------------------------------------------------------------

const POLL_MS = parseInt(process.env.EXAMPLE_POLL_MS ?? "3000", 10);
const TIMEOUT_MS = parseInt(process.env.EXAMPLE_TIMEOUT_MS ?? "600000", 10);

async function findTemplate(projectId, name) {
    const resp = await fetch(`${BASE_URL}/projects/${projectId}/document_templates/`, {
        headers: AUTH_HEADERS,
    });
    if (!resp.ok) throw new Error(`Discovery failed: ${resp.status} ${await resp.text()}`);
    const body = await resp.json();
    const template = body.results.find((t) => t.name === name);
    if (!template) throw new Error(`No template named "${name}" on project ${projectId}`);
    return template;
}

async function startGeneration(templateId, projectId, settings) {
    const resp = await fetch(`${BASE_URL}/document_templates/${templateId}/generate/`, {
        method: "POST",
        headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
        body: JSON.stringify({ project_id: projectId, settings }),
    });
    if (!resp.ok) throw new Error(`Generate failed: ${resp.status} ${await resp.text()}`);
    const body = await resp.json();
    return body.task_id;
}

function sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
}

async function waitForCompletion(taskId, { pollMs = POLL_MS, timeoutMs = TIMEOUT_MS } = {}) {
    const deadline = Date.now() + timeoutMs;
    while (true) {
        const resp = await fetch(`${BASE_URL}/document_template_tasks/${taskId}/`, {
            headers: AUTH_HEADERS,
        });
        if (!resp.ok) throw new Error(`Status failed: ${resp.status} ${await resp.text()}`);
        const status = await resp.json();
        if (status.state === "C") return status;
        if (status.state === "F") throw new Error(`Generation failed: ${status.state_message}`);
        if (Date.now() > deadline) throw new Error(`Task ${taskId} timed out`);
        console.log(
            `  state=${status.state} progress=${status.progress_pct}% — ${status.state_message}`,
        );
        await sleep(pollMs);
    }
}

async function download(status, savePath) {
    // The S3 URL is time-limited (see download.expires_in_seconds). If it has expired,
    // re-poll document_template_tasks/{taskId}/ to get a fresh URL for the same file.
    const { url, size_in_bytes } = status.download;
    // Note: do NOT send AUTH_HEADERS here — the signed URL authorises the request, and
    // adding an unrelated Authorization header can cause S3 to reject the download.
    const resp = await fetch(url);
    if (!resp.ok) throw new Error(`Download failed: ${resp.status} ${await resp.text()}`);
    const buffer = Buffer.from(await resp.arrayBuffer());
    await writeFile(savePath, buffer);
    console.log(`Saved ${size_in_bytes} bytes to ${savePath}`);
}

(async () => {
    const template = await findTemplate(PROJECT_ID, TEMPLATE_NAME);
    console.log(`Found template id=${template.id} (${template.template_type})`);

    const taskId = await startGeneration(template.id, PROJECT_ID, {
        include_inactive_forms: true,
        sort_by: "OID",
        report_title: "Q2 form audit",
    });
    console.log(`Started task ${taskId}`);

    const final = await waitForCompletion(taskId);
    await mkdir(OUTPUT_DIR, { recursive: true });
    await download(final, join(OUTPUT_DIR, final.download.filename));
})().catch((err) => {
    console.error(err);
    process.exit(1);
});
```

<a id="error-responses"></a>
## Error responses

| Status | Meaning |
| --- | --- |
| `400` | The request body was malformed — for example a missing `draft_id` / `project_id`, an invalid setting value, or a draft / project that doesn't belong to the template's URL. |
| `401` | Missing or invalid credentials. |
| `403` | You do not have permission to view the URL the template belongs to, or the project the draft belongs to. |
| `404` | The template, draft, project, or task does not exist (or, for the status endpoint, the task does not belong to you). |
| `405` | The template's scope is *Project Tickets*, which is not currently supported via the API. |
