# Grounded assistant chat

Operation ID: `patient.assistantChat`

Answer a free-text patient question using retrieval-augmented generation: ~8 candidate knowledge-base entries are retrieved via lexical keyword search, the LLM is grounded in them, and citations are rebuilt server-side from the model's cited source tags (the model can never fabricate citation fields). No authentication is required.

## Public method

`askAssistant`

Signature: `patient.askAssistant(request)`

Return type: `Promise<ChatResponse>`

## Authentication

Classification: **PUBLIC**

## Prerequisites

None documented.

## HTTP

`POST /assistant/chat`

## Path parameters

None.

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`AssistantChatRequest`](../models/AssistantChatRequest.md) | No |  |  |  | No |  |

Request model: [`AssistantChatRequest`](../models/AssistantChatRequest.md)

## Request example

```json
{
  "message": "What PPE should I wear?"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`AssistantChatResponse`](../models/AssistantChatResponse.md) | application/json | Grounded assistant answer |

## Success response examples

### 200

```json
{
  "answer": "For field screening, the standard PPE includes gloves, a surgical mask or N95 respirator, eye protection, and a disposable gown.",
  "citations": [
    {
      "collection": "ppe",
      "id": "kb_004",
      "title": "Standard PPE for field screening"
    }
  ],
  "disclaimer": "Informational and screening support only. This is not a diagnosis and not a substitute for a clinician or public-health authority.",
  "suggestedActions": []
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | message is missing or blank |
| `502` | `object` | application/json | The LLM call failed |
| `503` | `object` | application/json | The assistant is not configured (no OpenAI API key) |

## Error examples

### 400 — message is required

```json
{
  "error": "message is required"
}
```

### 502 — The LLM call raised an exception

```json
{
  "citations": [],
  "disclaimer": "Informational and screening support only. This is not a diagnosis and not a substitute for a clinician or public-health authority.",
  "error": "assistant_call_failed",
  "suggestedActions": []
}
```

### 503 — No LLM API key is configured for this deployment

```json
{
  "citations": [],
  "disclaimer": "Informational and screening support only. This is not a diagnosis and not a substitute for a clinician or public-health authority.",
  "error": "assistant_not_configured",
  "suggestedActions": []
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { ChatRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "message": "What PPE should I wear?"
};

const result = await patient.askAssistant(request);
```

## cURL

```bash
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"message":"What PPE should I wear?"}' \
  'https://dev-api-patient.health.cloud/assistant/chat'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.