---
title: "Generate a structured document"
method: POST
path: "/workspaces/{workspaceId}/consultations/{consultationId}/documents"
tags: ["consultations", "records"]
---

# Generate a structured document

`POST /workspaces/{workspaceId}/consultations/{consultationId}/documents`

## Request

- Base URL: `https://vetnio.com/api/v2`
- URL: `https://vetnio.com/api/v2/workspaces/{workspaceId}/consultations/{consultationId}/documents`
- Auth: HTTP bearer

Extracts the consultation into a JSON object that follows a JSON template's schema, for example to fill the fields of a practice-management system's journal entry.

First transcribes any uploaded recordings that have not been transcribed yet and waits for every recording on the consultation to finish (up to 10 minutes). The document is generated from the transcript and the consultation's additional info only: prompt templates, uploaded files, patient history and personal writing style are not used. Values are plain text taken from what was said; fields the conversation did not cover are left empty rather than invented.

The result is stored as the consultation's latest generated document, separately from the clinical note: it does not change the record returned by Get a record, and it cannot be read back through this API, so keep the response or callback body. Calling again generates and stores a new document.

**Synchronous (default):** blocks until the document is ready and returns it. A consultation with no transcript returns 400.

**Callback (`callbackUrl` set):** returns at once; the document or the error (including an empty transcript) is POSTed to the callback URL. Use it to avoid holding a connection open. Both modes share a 10-minute limit for the whole job, transcription wait included; a job cut off by that limit returns a gateway timeout in synchronous mode and sends no callback at all in callback mode.

An unknown `jsonTemplateId` returns 404 in both modes, before anything is generated. Requires a personal API key and write access to the consultation; archived consultations return 403. Not idempotent: every call runs the AI model again.

## Path parameters

- `workspaceId` string, required: Identifier of the clinic (workspace), as returned by `GET /workspaces`. The key's user must be a member of the clinic, or an admin of the organization it belongs to.
- `consultationId` string, required: Identifier of the consultation (UUID), as returned when it was created or by `GET /workspaces/{workspaceId}/consultations`. It must belong to the clinic in `workspaceId`.

## Request body

- object
  - `jsonTemplateId` string, required: ID of the JSON template (structured template) whose schema the document must follow, from List JSON templates. Must be one of this workspace's JSON templates or a built-in one; otherwise 404.
  - `callbackUrl` string, uri: Absolute URL (use HTTPS) that switches the request to callback mode: the response returns immediately with `message: "Callback URL has been queued"`, and the outcome is POSTed to this URL as JSON once transcription and generation finish. Each callback has an `X-Vetnio-Callback-Status` header of `success` (body: the document object) or `error` (body `{ "error": { "code", "message" }, "workspaceId", "consultationId" }`). One attempt with a 30-second timeout and no retries; callbacks are not signed, so put a secret token in the URL if you need to authenticate them.
  - `languageCode` 'sv' | 'en' | 'af' | 'am' | 'ar' | 'hy' | 'as' | 'ast' | 'az' | 'be' | 'bn' | 'bs' | 'bg' | 'my' | 'yue' | 'ca' | 'ceb' | 'ny' | 'zh' | 'hr' | 'cs' | 'da' | 'nl' | 'et' | 'fil' | 'fi' | 'fr' | 'ff' | 'gl' | 'lg' | 'ka' | 'de' | 'el' | 'gu' | 'ha' | 'he' | 'hi' | 'hu' | 'is' | 'ig' | 'id' | 'ga' | 'it' | 'ja' | 'jv' | 'kea' | 'kn' | 'kk' | 'km' | 'ko' | 'ku' | 'ky' | 'lo' | 'lv' | 'ln' | 'lt' | 'luo' | 'lb' | 'mk' | 'ms' | 'ml' | 'mt' | 'mi' | 'mr' | 'mn' | 'ne' | 'nso' | 'no' | 'oc' | 'or' | 'ps' | 'fa' | 'pl' | 'pt' | 'pa' | 'ro' | 'ru' | 'sr' | 'sn' | 'sd' | 'sk' | 'sl' | 'so' | 'es' | 'sw' | 'tl' | 'ta' | 'tg' | 'te' | 'th' | 'tr' | 'uk' | 'umb' | 'ur' | 'uz' | 'vi' | 'cy' | 'wo' | 'xh' | 'zu': Language to write the document in, as a recording-language code (mostly ISO 639-1, for example `sv`, `en`, `de`, `no`; a few three-letter codes such as `yue` or `fil`). The transcript can be in another language. When omitted, the consultation's recording language is used; if the consultation has none, the model chooses.

## Response `200`

Synchronous mode: the generated document object. Callback mode: `{ "message": "Callback URL has been queued" }`.

- unknown

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `500`: Internal server error

---

[API](https://skmtc.dev/vetnio/apis/vetnio-api.md) - [All operations](https://skmtc.dev/vetnio/apis/vetnio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vetnio/apis/vetnio-api/revisions/d004afd5617d?raw)