AgentChatResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vera-health/json-schema/vera-health-agent-chat-response-schema.json",
  "title": "AgentChatResponse",
  "description": "Non-streaming response (`stream: false`).",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vera-health-openapi.json#/components/schemas/AgentChatResponse",
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "format": "uuid",
      "description": "The thread this answer is saved in. Same value as the `x-thread-id` header."
    },
    "message_id": {
      "type": "string",
      "format": "uuid",
      "description": "The id the answer is saved under. A refused request never reaches this body: it returns `422 content_policy_stop`."
    },
    "answer": {
      "type": "string",
      "description": "The answer in Markdown, carrying the same citation markup the stream does: a `<cite index=\"5-1\">claim</cite>` tag names the `sourceId` of the reference behind the claim (the number before the dash). Empty when the agent's deliverable is a tool payload: see `tool_outputs`."
    },
    "references": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentReference"
      }
    },
    "tool_outputs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentToolOutput"
      }
    },
    "suggestions": {
      "$ref": "#/$defs/AgentSuggestedQuestions",
      "description": "Present only when the request set `suggestions: true`."
    }
  },
  "$defs": {
    "AgentReference": {
      "type": "object",
      "properties": {
        "sourceId": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "The number before the dash in a `cite index`, and the whole index of a `figure` or `calculator` placement."
        },
        "kind": {
          "type": "string",
          "enum": [
            "paper",
            "drug",
            "figure",
            "calculator"
          ],
          "description": "What the source is. `paper` covers journal articles and guidelines; `drug` a monograph; `figure` an image the answer places; `calculator` a computed score."
        },
        "title": {
          "type": "string",
          "description": "Paper or guideline title, drug name, figure caption, or calculator name."
        },
        "firstAuthor": {
          "type": "string",
          "description": "Papers only."
        },
        "journal": {
          "type": "string",
          "description": "Papers only."
        },
        "year": {
          "type": "string",
          "description": "Papers only."
        },
        "doi": {
          "type": "string",
          "description": "Papers only. Absent when the paper has none."
        },
        "imageUrl": {
          "type": "string",
          "description": "Figures only: the image a `figure` placement renders. Fetch it while rendering the answer rather than storing the link: the URL is not part of this contract and may change or stop resolving at any time."
        },
        "isGuideline": {
          "type": "boolean",
          "description": "Papers only: whether the source is a clinical guideline rather than a primary study. Absent on drug, figure and calculator sources."
        },
        "evidenceStrength": {
          "type": "string",
          "enum": [
            "Very High",
            "High",
            "Moderate",
            "Low"
          ],
          "description": "Graded level of evidence for the paper. Absent when it has none."
        }
      },
      "required": [
        "sourceId",
        "kind"
      ],
      "description": "A source the answer drew on. Every reference is citable: `sourceId` is the number a `cite`, `figure` or `calculator` index in the answer resolves to."
    },
    "AgentSuggestedQuestions": {
      "type": "object",
      "description": "Three follow-up questions derived from the question and the answer.",
      "properties": {
        "question_1": {
          "type": "string"
        },
        "question_2": {
          "type": "string"
        },
        "question_3": {
          "type": "string"
        }
      },
      "required": [
        "question_1",
        "question_2",
        "question_3"
      ]
    },
    "AgentToolOutput": {
      "type": "object",
      "required": [
        "tool",
        "output"
      ],
      "description": "One reported tool call. Only the tools below report a payload; retrieval, the drug lookup and the bibliographic lookups do their work on the model channel and reach you as references and answer text. Each payload is trimmed to its documented fields at every depth before it leaves the server.",
      "properties": {
        "tool": {
          "type": "string",
          "enum": [
            "medcalc",
            "patientHandout",
            "priorAuth"
          ]
        },
        "output": {
          "oneOf": [
            {
              "$ref": "#/$defs/AgentToolPayloadMedcalc"
            },
            {
              "$ref": "#/$defs/AgentToolPayloadPatientHandout"
            },
            {
              "$ref": "#/$defs/AgentToolPayloadPriorAuth"
            }
          ]
        }
      }
    },
    "AgentToolPayloadMedcalc": {
      "type": "object",
      "properties": {
        "calcId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "inputs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "value"
            ]
          }
        },
        "sourceId": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "calcId",
        "title"
      ],
      "description": "The `medcalc` tool's payload: which calculator ran, the inputs it resolved from the question, and the `sourceId` a `calculator` placement in the answer resolves to."
    },
    "AgentToolPayloadPatientHandout": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "content": {
          "type": "string"
        },
        "language": {
          "type": "string"
        }
      },
      "required": [
        "title",
        "content"
      ],
      "description": "The `patientHandout` tool's deliverable: the document the model authored, in Markdown. On these turns `answer` is empty."
    },
    "AgentToolPayloadPriorAuth": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "content": {
          "type": "string"
        }
      },
      "required": [
        "title",
        "content"
      ],
      "description": "The `priorAuth` tool's deliverable: the letter the model authored, in Markdown. On these turns `answer` is empty."
    }
  }
}