--- title: "Generate a structured document" method: POST path: "/documents/" tags: ["Guided Documents"] --- # Generate a structured document `POST /documents/` Generates a structured document using one of three template-supply paths: a stored template reference (optionally with runtime overrides), an ad-hoc assembly of stored sections, or a fully inline dynamic template. Exactly one of `templateRef`, `assemblyTemplate`, or `dynamicTemplate` must be provided. Context can combine different types or reference an interactionId to automatically fetch existing context to pass to the LLM. Note that discarded facts are not passed to the LLM. With the exception of the plain `templateRef` path (no overrides), every call creates a new auto-generated template aggregate that snapshots the resolved prompts as a drift-proof receipt, persisted for 30 days. ## Headers - `Tenant-Name` string, required — Identifies a distinct entity within Corti's multi-tenant system. Ensures correct routing and authentication of the request. - `X-Corti-Retention-Policy` 'none' ## Request body - union - GuidedDocumentsGenerateByTemplateRef — Fields shared across all guided-document request variants. `outputLanguage` is always required. Exactly one of `context` (possible to combine different context types) or `interactionId` (API auto-fetches existing facts, transcripts) must be supplied as input for the model. - `outputLanguage` string, required — The language in which the document will be generated as a BCP 47 tag. - `context` GuidedDocumentContext[] — Ordered list of context items the model reasons over. Each item is one of text, a transcript (with optional metadata and segments), or a single fact. Items are interleaved by timestamps where present on transcript segments; otherwise array order is preserved. - union - CommonTextContext - `type` 'text', required — The type of context, always "text" in this context. - `text` string, required — A text string to be used as input to the model. - CommonTranscriptContext — A transcript provided as input context to the model. - `type` 'transcript', required - `transcript` GuidedDocumentTranscriptMinimal, required — Minimal transcript shape accepted as guided-document input context. Decoupled from the transcript resource: only `transcripts` is required, and within each segment only `text` is required. - `metadata` GuidedDocumentTranscriptMetadataMinimal — Optional transcript-level metadata. All fields optional. - … - `transcripts` GuidedDocumentTranscriptSegmentMinimal[], required - … - CommonFactsContext — A list of facts provided as input context to the model. - `type` 'facts', required - `facts` GuidedDocumentFactMinimal[], required - `text` string, required — The text of the fact. - `group` string — The group to which the fact belongs. - `interactionId` string, uuid — When supplied, all facts and transcripts already attached to the referenced interaction are passed implicitly as input context. Facts with `isDiscarded: true` are not passed on. - `labels` GuidedLabel[] — Key/value labels attached to the document. Used for filtering in the LIST /documents endpoint. - `key` string, required - `value` string, required - `templateRef` GuidedTemplateRef, required - `templateId` string, uuid, required — The UUID of a stored template. - `templateVersionId` string, uuid, nullable — Optional explicit template version. Defaults to the template's published version when omitted. - `overrides` GuidedTemplateOverrides - `instructions` GuidedTemplateInstructions - `prompt` string, required — Template-level prompt instructions that apply generally to all sections. - `sections` GuidedSectionOverride[] — Per-section override patches. Each entry must reference a section already linked to the base template version. - `sectionId` string, uuid, required — The UUID of a section linked to the base template version. - `generation` GuidedSectionOverrides — Patches a section's content at link time without mutating the underlying section. Override semantics are per-field for instructions (any field you omit is inherited from the parent's published version) and wholesale for `outputSchema` (whatever you submit fully replaces the parent schema). The same applies when a section is forked via `inheritFromId`. - `heading` string, nullable — When provided, replaces the section's heading for this call. - `instructions` GuidedSectionInstructionsOverride — Partial section-instructions patch used in override and fork contexts. Each field is independent: provide only the fields you want to replace, and any field you omit is inherited from the parent's published version. - … - `outputSchema` union - … - GuidedDocumentsGenerateByAssembly — Fields shared across all guided-document request variants. `outputLanguage` is always required. Exactly one of `context` (possible to combine different context types) or `interactionId` (API auto-fetches existing facts, transcripts) must be supplied as input for the model. - `outputLanguage` string, required — The language in which the document will be generated as a BCP 47 tag. - `context` GuidedDocumentContext[] — Ordered list of context items the model reasons over. Each item is one of text, a transcript (with optional metadata and segments), or a single fact. Items are interleaved by timestamps where present on transcript segments; otherwise array order is preserved. - union - CommonTextContext - `type` 'text', required — The type of context, always "text" in this context. - `text` string, required — A text string to be used as input to the model. - CommonTranscriptContext — A transcript provided as input context to the model. - `type` 'transcript', required - `transcript` GuidedDocumentTranscriptMinimal, required — Minimal transcript shape accepted as guided-document input context. Decoupled from the transcript resource: only `transcripts` is required, and within each segment only `text` is required. - `metadata` GuidedDocumentTranscriptMetadataMinimal — Optional transcript-level metadata. All fields optional. - … - `transcripts` GuidedDocumentTranscriptSegmentMinimal[], required - … - CommonFactsContext — A list of facts provided as input context to the model. - `type` 'facts', required - `facts` GuidedDocumentFactMinimal[], required - `text` string, required — The text of the fact. - `group` string — The group to which the fact belongs. - `interactionId` string, uuid — When supplied, all facts and transcripts already attached to the referenced interaction are passed implicitly as input context. Facts with `isDiscarded: true` are not passed on. - `labels` GuidedLabel[] — Key/value labels attached to the document. Used for filtering in the LIST /documents endpoint. - `key` string, required - `value` string, required - `assemblyTemplate` GuidedAssemblyRequest, required — Compose a template by referencing existing stored sections in declaration order. - `name` string, required — Name for the auto-generated template aggregate that will be persisted. - `instructions` GuidedTemplateInstructions - `prompt` string, required — Template-level prompt instructions that apply generally to all sections. - `sectionRefs` GuidedAssemblySectionRef[], required - `sectionId` string, uuid, required - `sectionVersionId` string, uuid, nullable — Optional explicit section version. Defaults to the section's published version when omitted. - `overrides` GuidedSectionOverrides — Patches a section's content at link time without mutating the underlying section. Override semantics are per-field for instructions (any field you omit is inherited from the parent's published version) and wholesale for `outputSchema` (whatever you submit fully replaces the parent schema). The same applies when a section is forked via `inheritFromId`. - `heading` string, nullable — When provided, replaces the section's heading for this call. - `instructions` GuidedSectionInstructionsOverride — Partial section-instructions patch used in override and fork contexts. Each field is independent: provide only the fields you want to replace, and any field you omit is inherited from the parent's published version. - `contentPrompt` string — When provided, replaces the section's content prompt. Omit to inherit from the parent. - `writingStylePrompt` string — When provided, replaces the section's writing style prompt. Omit to inherit from the parent. - `miscPrompt` string — When provided, replaces the section's misc prompt. Omit to inherit from the parent. - `outputSchema` union - GuidedStringNode - … - GuidedNumberNode - … - GuidedBoolNode - … - GuidedArrayNode - … - GuidedObjectNode - … - GuidedDocumentsGenerateByDynamic — Fields shared across all guided-document request variants. `outputLanguage` is always required. Exactly one of `context` (possible to combine different context types) or `interactionId` (API auto-fetches existing facts, transcripts) must be supplied as input for the model. - `outputLanguage` string, required — The language in which the document will be generated as a BCP 47 tag. - `context` GuidedDocumentContext[] — Ordered list of context items the model reasons over. Each item is one of text, a transcript (with optional metadata and segments), or a single fact. Items are interleaved by timestamps where present on transcript segments; otherwise array order is preserved. - union - CommonTextContext - `type` 'text', required — The type of context, always "text" in this context. - `text` string, required — A text string to be used as input to the model. - CommonTranscriptContext — A transcript provided as input context to the model. - `type` 'transcript', required - `transcript` GuidedDocumentTranscriptMinimal, required — Minimal transcript shape accepted as guided-document input context. Decoupled from the transcript resource: only `transcripts` is required, and within each segment only `text` is required. - `metadata` GuidedDocumentTranscriptMetadataMinimal — Optional transcript-level metadata. All fields optional. - … - `transcripts` GuidedDocumentTranscriptSegmentMinimal[], required - … - CommonFactsContext — A list of facts provided as input context to the model. - `type` 'facts', required - `facts` GuidedDocumentFactMinimal[], required - `text` string, required — The text of the fact. - `group` string — The group to which the fact belongs. - `interactionId` string, uuid — When supplied, all facts and transcripts already attached to the referenced interaction are passed implicitly as input context. Facts with `isDiscarded: true` are not passed on. - `labels` GuidedLabel[] — Key/value labels attached to the document. Used for filtering in the LIST /documents endpoint. - `key` string, required - `value` string, required - `dynamicTemplate` GuidedDynamicRequest, required — Fully inline template definition. Sections and the wrapping template are created and immediately published as auto-generated resources. - `name` string, required - `generation` GuidedDynamicInline, required - `instructions` GuidedTemplateInstructions, required - `prompt` string, required — Template-level prompt instructions that apply generally to all sections. - `sections` GuidedSectionGeneration[], required - `heading` string, required — The heading of this section. Passed to the LLM. - `instructions` GuidedSectionInstructions, required - `contentPrompt` string, required — The content prompt instructs the model what to include for synthesis. For `documentationMode: routed_parallel` this impacts what facts to route to this section. - `writingStylePrompt` string — The writingStyle prompt instructs the model in what tone and style to output. - `miscPrompt` string — Optional free-form prompt for any instructions that don't fit contentPrompt or writingStylePrompt. - `outputSchema` union, required - GuidedStringNode - … - GuidedNumberNode - … - GuidedBoolNode - … - GuidedArrayNode - … - GuidedObjectNode - … ## Response `200` OK — document was generated but not saved (retention policy `none`). - GuidedDocumentsCreateEphemeralResponse — Response when a document is generated but not saved (retention policy `none`). - `document` GuidedEphemeralDocument, required — A generated document that was not saved to the database. - `name` string, required - `templateId` string, uuid, required - `templateVersionId` string, uuid, required - `language` string, required — The BCP 47 language tag of the generated output. - `interactionId` string, uuid, nullable — The interaction whose context was used to generate this document, if supplied. - `stringDocument` object, required - `structuredDocument` object, nullable - `labels` GuidedLabel[], required — Key/value labels attached to this document. - `key` string, required - `value` string, required - `usageInfo` CommonUsageInfo, required — Credits consumed for this request. - `creditsConsumed` number, required ## Other responses - `201` — Created — document was generated and saved. - `400` — Bad Request - `404` — Referenced template, template version, or section was not found. - `422` — Request was syntactically valid but semantically rejected — for example, none of `templateRef`/`assemblyTemplate`/`dynamicTemplate` was supplied, the referenced template has no published version, or an override referenced a section that is not part of the base template. - `500` — The downstream ML service failed to generate the document. --- [API](https://skmtc.net/corti/apis/admin-api.md) · [All operations](https://skmtc.net/corti/apis/admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/corti/admin-api/versions/5d1895a1b3fc/schema)