--- title: "Generate a clinical note" method: POST path: "/workspaces/{workspaceId}/consultations/{consultationId}/clinical-note/generate" tags: ["consultations", "records"] --- # Generate a clinical note `POST /workspaces/{workspaceId}/consultations/{consultationId}/clinical-note/generate` ## Request - Base URL: `https://vetnio.com/api/v2` - URL: `https://vetnio.com/api/v2/workspaces/{workspaceId}/consultations/{consultationId}/clinical-note/generate` - Auth: HTTP bearer Writes the consultation's clinical note with AI and saves it as the current version of the record (`changeType: generated` in version history). 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). Generation then uses the full transcript, the consultation's additional info and uploaded files, the selected template, the linked patient's details and earlier visits, the clinic-wide and personal writing instructions, the user's learned writing style, and the recording language. Generation itself usually takes well under a minute. **Synchronous (default):** the request blocks until the note is saved and returns it in `clinicalNote`. If the consultation's clinical note uses a structured template, the response is `message: "Structured document generation initiated"` and the note is generated in the background; poll the consultation until `isGeneratingClinicalNote` is `false`, then read the record. A consultation with no transcript returns 400. **Callback (`callbackUrl` set):** returns at once; the note 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. Side effects: the consultation's selected template is updated when `templateId` is given, the consultation's AI title may be refreshed, and the consultation is marked as submitted. Not idempotent: every call runs the AI model again and adds a version. Requires a personal API key and write access to the consultation; archived consultations return 403. ## 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 - `templateId` string: ID of the template (from List templates) whose sections and instructions shape the note. The template is also saved as the consultation's selected clinical-note template. When omitted, the template already selected on the consultation is used, or none if it has none. Pass `auto` to generate without a template and clear the selection. An ID that does not belong to this workspace is not rejected: the note is generated without a template and the selection is cleared. The template's type is not checked, so pass a Clinical Note template. - `shouldGenerateFromScratch` boolean: Defaults to `true`: write a new note from the full transcript, replacing the current one. Set `false` to update the existing note instead, keeping its content (including manual edits) and adding what was said in recordings transcribed since the last generation. Vetnio falls back to from-scratch when there is no existing note or when `templateId` names a different template than the consultation's current one. - `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 `{ "clinicalNote": "" }`; for a structured-template note the body is `{}` and is sent as soon as background generation starts, so read the record once `isGeneratingClinicalNote` is `false`) 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. ## Response `200` Synchronous free-text generation: the saved note in `clinicalNote`. Callback mode or structured-template notes: a status `message`. - GenerateClinicalNoteOutput: Exactly one of `clinicalNote` (synchronous free-text generation) or `message` (callback mode, or a structured-template note still generating) is present. - `message` string: Present instead of `clinicalNote` when the note is not returned in this response: - `Callback URL has been queued` — you passed `callbackUrl`; the outcome will be POSTed to it. - `Structured document generation initiated` — the consultation's clinical note uses a structured template and is being generated in the background. Poll `GET /workspaces/{workspaceId}/consultations/{consultationId}` until `isGeneratingClinicalNote` is `false`, then read the record. - `clinicalNote` string: The generated clinical note as HTML, returned in synchronous mode for free-text notes. Generated notes use `` section headings, `
` line breaks and `•` bullet characters rather than heading, paragraph or list elements. The note has already been saved as the consultation's clinical note. ## 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)