vetsgpt

Send a message to VetsGPT

Sends one message to VetsGPT, waits for the complete answer and returns both stored messages as JSON (no streaming). It runs the same engine as the web app: the message is classified as clinical or administrative, clinical questions are answered from web and clinic-knowledge search with inline citations, and the chat's consultation, patient and file context is included. An answer involves several model calls and searches, so expect responses to take a while and use a long client timeout.

Omit chatId to start a chat (its id is derived from idempotencyKey), or pass an existing chat's id to continue it. The caller must own the chat or have contribute access. Only the owner can send consultationIds or patientId to update its context before a new question; contributors must omit both.

Idempotency: every request needs an idempotencyKey. Repeating a request with the same key returns the stored answer without generating again. With server-coordinated turns, changing the prompt, files or generation options under the same key is a conflict. If an earlier request with that key is still generating, the call waits for it, and returns 409 CONFLICT if it does not finish. If generation fails, the question stays stored and requires an explicit retry: true action by the original sender to restart the latest interrupted request before later messages. The question retains its original linked context. Ordinary network replay never restarts it. 409 CHAT_BUSY means another question is generating; REQUEST_MISMATCH means the payload changed under the same key; RETRY_NOT_ALLOWED means an explicit retry can no longer restart.

Deep Research, streaming, and the consultation editor actions of the web app are not available through this endpoint. The first VetsGPT use in a workspace without a subscription can start its free trial. Errors: 403 when VetsGPT is disabled for the caller, 404 for an unknown chat, insufficient chat permission or an unreadable consultation, 500 when generation fails.

post/workspaces/{workspaceId}/vetsgpt/ask

Request

Base URL
https://vetnio.com/api/v2
URL
https://vetnio.com/api/v2/workspaces/{workspaceId}/vetsgpt/ask
Auth
HTTP bearer

Path parameters

workspaceIdstring required

Identifier of the workspace (clinic). The caller must be a member, and VetsGPT must be enabled for them in this workspace.

Example:furunculotic-loud-chihuahua

Request body

chatIdstring

Existing chat the caller owns or has contribute access to; 404 if it does not exist. Omit to start a new chat, whose id is derived from idempotencyKey. A chat must already exist to upload attachments, so create it first when the first message carries files.

titlestring

Initial title for a chat created by this call; ignored when chatId is given. VetsGPT replaces it with a generated title after the first message on a topic. Defaults to New Chat <date>.

messagestring required

The vet's question or instruction, as plain text (1 to 50,000 characters).

retryboolean

Explicitly retry the latest interrupted turn; network replays must omit this.

idempotencyKeystring required

Client-generated unique key for this message (8 to 128 characters, for example a UUID). Retrying with the same key never sends the question twice: if the answer is already stored it is returned immediately, and if another request with this key is still generating, this one waits for it. Use a new key for every new message.

consultationIdsstring[]

Owner only: consultations to use for a new question (up to 50). A non-empty list replaces the chat's stored consultation context; when omitted or empty, the existing context is kept. Contributors must omit this field. Replays and explicit retries retain the original question's context. VetsGPT sees each consultation's name, date, transcript, clinical note, client communication and linked patient. Every id must be readable by the caller, otherwise 404.

patientIdstring

Owner only: patient to store as context for a new question, replacing any previous one. Contributors must omit this field. VetsGPT uses the patient's basic details, up to five recent clinical notes and analysed patient files only while no consultations are attached. The id is not validated; an unknown id gives no context. Omit to keep the stored patient. Replays and explicit retries retain the original question's context.

imageKeysstring[]

Keys of images uploaded to this chat through the upload-url endpoint. VetsGPT reads each file for this message only; send the keys again to use a file in a later message. Keys from another chat or user are ignored, as are files with an unsupported Content-Type.

pdfKeysstring[]

Keys of PDF documents uploaded to this chat through the upload-url endpoint. Handled exactly like imageKeys (the stored Content-Type decides how the file is read).

categoryHint'clinical' | 'administrative'

Overrides VetsGPT's automatic classification of the question:

clinical — answer as a clinical question, with web and clinic-knowledge search and citations.
administrative — answer as a practice-administration task (for example drafting a summary or referral) without web search. Omit to let VetsGPT classify the message itself.

Example request

{
  "chatId": "3f9c2a71-5b8e-4d1a-9c47-0e6b2d8f1a53",
  "title": "NSAID dosing in a dog with CKD",
  "message": "What is the meloxicam dose for a 24 kg dog with stage 2 CKD?",
  "idempotencyKey": "0b7f6a52-93c1-4e2d-8a4f-61d0c9e3b7aa",
  "consultationIds": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "patientId": "f2a3b4c5-d6e7-4890-fabc-012345678901",
  "imageKeys": [
    "chats/furunculotic-loud-chihuahua/3f9c2a71-5b8e-4d1a-9c47-0e6b2d8f1a53/attachments/6a1e0f3c-2b9d-4c7e-8f5a-1d3b9e7c2a40"
  ],
  "pdfKeys": [
    "chats/furunculotic-loud-chihuahua/3f9c2a71-5b8e-4d1a-9c47-0e6b2d8f1a53/attachments/9c2b7e14-5f3a-4d8b-a1e6-0f7c3d9b2e58"
  ],
  "categoryHint": "clinical"
}

Response

The persisted user message and completed VetsGPT answer.

progressEventsstring[] required

Progress phases VetsGPT went through while generating this answer, in order:

analyzing_question — preparing a clinical question for search.
searching_sources — searching the web and the clinic's knowledge material.
generating_answer — writing the answer. A clinical question normally reports all three; administrative and conversational messages may report none. Empty when the answer came from an earlier request with the same idempotencyKey. Informational only.

Example response

{
  "chat": {
    "chatId": "rest-chat-4b1f0c9e2d7a4e6b8c3f5a1d9e0b2c7f",
    "title": "NSAID dosing in a dog with CKD",
    "createdAt": "2026-10-04T09:12:31.000Z",
    "updatedAt": "2026-10-04T09:12:58.000Z"
  },
  "userMessage": {
    "messageId": "rest-assistant-message-9d2e7c1b4a6f8e0d3c5b7a9f1e2d4c6b",
    "timestamp": "2026-10-04T09:12:58.000Z",
    "role": "assistant",
    "content": "Meloxicam is generally avoided in dogs with CKD unless the benefit outweighs the risk...",
    "attachments": [
      "chats/furunculotic-loud-chihuahua/3f9c2a71-5b8e-4d1a-9c47-0e6b2d8f1a53/attachments/6a1e0f3c-2b9d-4c7e-8f5a-1d3b9e7c2a40"
    ],
    "feedback": "none"
  },
  "assistantMessage": {
    "messageId": "rest-assistant-message-9d2e7c1b4a6f8e0d3c5b7a9f1e2d4c6b",
    "timestamp": "2026-10-04T09:12:58.000Z",
    "role": "assistant",
    "content": "Meloxicam is generally avoided in dogs with CKD unless the benefit outweighs the risk...",
    "attachments": [
      "chats/furunculotic-loud-chihuahua/3f9c2a71-5b8e-4d1a-9c47-0e6b2d8f1a53/attachments/6a1e0f3c-2b9d-4c7e-8f5a-1d3b9e7c2a40"
    ],
    "feedback": "none"
  },
  "progressEvents": [
    "analyzing_question",
    "searching_sources",
    "generating_answer"
  ]
}

Changes

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