AgentChatRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vera-health/json-schema/vera-health-agent-chat-request-schema.json",
  "title": "AgentChatRequest",
  "description": "Request envelope for `POST /api/chat/v3`.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vera-health-openapi.json#/components/schemas/AgentChatRequest",
  "type": "object",
  "required": [
    "question"
  ],
  "properties": {
    "question": {
      "type": "string",
      "minLength": 1,
      "description": "The clinical question to answer."
    },
    "thread_id": {
      "type": "string",
      "format": "uuid",
      "description": "Continue an existing conversation. Pass the `x-thread-id` (or `thread_id`) of an earlier answer to ask a follow-up in that thread. Omit it to start a new thread. Only threads created with your partner account can be continued; any other id returns 404."
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentToolId"
      },
      "description": "Optional tools to enable for this request. **Omitting the field and sending an empty array are equivalent**: both leave every switchable tool off, and the agent answers with the always-on retrieval tools alone. There is no per-key default set. Duplicates are collapsed. An unknown id returns 400; an id your key is not provisioned for returns 403."
    },
    "country": {
      "type": "string",
      "enum": [
        "FR",
        "IT"
      ],
      "description": "Jurisdiction of the clinician, ISO 3166-1 alpha-2. Only the jurisdictions whose national authority publishes in its own language are accepted, because only those change the answer. Case-insensitive. Omit it and no jurisdiction weighting is applied."
    },
    "stream": {
      "type": "boolean",
      "default": true,
      "description": "`true` (default) streams the AI SDK UI message stream. `false` returns a single JSON payload."
    },
    "suggestions": {
      "type": "boolean",
      "default": false,
      "description": "Ask for three follow-up questions derived from the answer. With `stream: false` they arrive in the `suggestions` field of the JSON body; a streamed turn emits them as a `data-suggestions` event. Both lanes send them only when this is `true`. Off by default because they are a second model call made after the answer is already complete, and a request/response caller waits for it."
    }
  },
  "$defs": {
    "AgentToolId": {
      "type": "string",
      "description": "A tool you can switch on or off per request. Literature retrieval is always on and is not listed here: it cannot be disabled.",
      "enum": [
        "drug",
        "medcalc",
        "patientHandout",
        "priorAuth"
      ],
      "x-enum-descriptions": {
        "drug": "Drug monograph lookup: dosing, interactions, and labelling.",
        "medcalc": "Clinical calculators: resolves and computes a score from the question.",
        "patientHandout": "Patient-facing care instructions. Delivered as tool input; the answer text stays empty.",
        "priorAuth": "Prior-authorization letter. Delivered as tool input; the answer text stays empty."
      }
    }
  }
}