Generate a clinical note

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.

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

Path parameters

workspaceIdstring 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.

Example:furunculotic-loud-chihuahua

consultationIdstring 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.

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Request body

templateIdstring

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.

shouldGenerateFromScratchboolean

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.

callbackUrlstring 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": "<html>" }; 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.

Example request

{
  "templateId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f9a6c13",
  "callbackUrl": "https://pms.example.com/webhooks/vetnio/clinical-note?token=9f2c7e"
}

Response

Synchronous free-text generation: the saved note in clinicalNote. Callback mode or structured-template notes: a status message.

messagestring

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.

clinicalNotestring

The generated clinical note as HTML, returned in synchronous mode for free-text notes. Generated notes use <strong> section headings, <br /> line breaks and • bullet characters rather than heading, paragraph or list elements. The note has already been saved as the consultation's clinical note.

Example response

{
  "message": "Callback URL has been queued",
  "clinicalNote": "<strong>History</strong><br />Bella, an 8-year-old Labrador, has had intermittent left hind lameness for 2 weeks.<br /><br /><strong>Examination</strong><br />• T 38.6 °C<br />• Mild pain on extension of the left stifle<br /><br /><strong>Plan</strong><br />• Carprofen 2 mg/kg PO q12h for 7 days<br />• Recheck in 14 days"
}

Changes

No recorded changes to this operation across all 1 revision of this API.