Path 1 — Plain `templateRef`

Reference a stored, published template by UUID. The lightest path on POST /documents — no side-effects, no auto-generated aggregate, ideal for production traffic.

Beta

← Back to Guided Synthesis overview

Use this when a published template already encodes everything you need. The base template is not modified, and no new template is persisted as a side-effect of the call. This is the lightest path — ideal for production traffic.

JavaScript

// Replace these with your values
const INTERACTION_ID = "<your-interaction-id>";
const TEMPLATE_ID = "<your-template-id>";

const result = await client.documents.generate({
  outputLanguage: "en-US",
  interactionId: INTERACTION_ID,
  templateRef: { templateId: TEMPLATE_ID },
});

using Corti;

// Replace these with your values
const string InteractionId = "<your-interaction-id>";
const string TemplateId = "<your-template-id>";

var result = await client.Documents.GenerateAsync(
    new GuidedDocumentsGenerateByTemplateRef
    {
        OutputLanguage = "en-US",
        InteractionId = InteractionId,
        TemplateRef = new GuidedTemplateRef { TemplateId = TemplateId },
    });

import requests

# Replace these with your values
ENVIRONMENT = "<eu-or-us>"
INTERACTION_ID = "<your-interaction-id>"
TEMPLATE_ID = "<your-template-id>"
TENANT = "<your-tenant-name>"
TOKEN = "<your-access-token>"

response = requests.post(
    f"https://api.{ENVIRONMENT}.corti.app/v2/documents",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Tenant-Name": TENANT,
        "Content-Type": "application/json",
    },
    json={
        "outputLanguage": "en-US",
        "interactionId": INTERACTION_ID,
        "templateRef": {"templateId": TEMPLATE_ID},
    },
)
response.raise_for_status()
result = response.json()

# Replace these with your values
ENVIRONMENT="<eu-or-us>"
INTERACTION_ID="<your-interaction-id>"
TEMPLATE_ID="<your-template-id>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl --request POST \
  --url "https://api.${ENVIRONMENT}.corti.app/v2/documents" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Tenant-Name: ${TENANT}" \
  --header "Content-Type: application/json" \
  --data "{
    \"outputLanguage\": \"en-US\",
    \"interactionId\": \"${INTERACTION_ID}\",
    \"templateRef\": { \"templateId\": \"${TEMPLATE_ID}\" }
  }"

Pin a specific version when you need reproducibility against a known version (otherwise the template’s currently published version is used):

"templateRef": {
  "templateId":        "<your-template-id>",
  "templateVersionId": "<your-version-id>"
}

When to use this path

Scenario	Why Path 1
Production ambient flow where every encounter uses the same template	Reproducible, fastest, no auto-generated aggregate to manage.
You want full traceability via a known templateVersionId	Pin the version explicitly — the response’s templateId / templateVersionId match your request.
You have no per-call tweaks today	If a tweak becomes needed later, you can move to Path 2 (templateRef + overrides) without changing the rest of your integration.

If you’re new to Guided Synthesis, this is the path to start with. Once it works end-to-end, layer in overrides (Path 2) or assembly (Path 3) as your use case grows.

Related

Guided Synthesis overview

Shared concepts: input context, response shape, errors, 30-day retention.

Path 2 — templateRef + overrides

Keep your base template, patch a section’s title, instructions or schema for a single call.