# ai

Canonical page: https://docs.ovok.com/settings-and-features/features/ai

Lets the project call a hosted language model through the FHIR API's `$ai` operation. Each call uses **your own OpenAI API key**, sent in the request.

| | |
| --- | --- |
| Type | Project feature |
| Value in `features` | `ai` |
| Change with | `PATCH /v1/projects/me/features` (replaces the whole list) |
| Who can change it | Project admin. Any practitioner can read the list. |
| On for new projects | **No** |
| When off | `POST /fhir/R4/$ai` answers `403` `Forbidden` |

## What it enables [#what-it-enables]

`POST /fhir/R4/$ai` sends a conversation to OpenAI's chat completions service and returns the answer.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/$ai' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @ai-parameters.json
```

Example `ai-parameters.json`:

```json
{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "messages", "valueString": "[{\"role\":\"user\",\"content\":\"Summarise: patient reports mild headache.\"}]" },
    { "name": "apiKey", "valueString": "<your OpenAI API key>" },
    { "name": "model", "valueString": "gpt-4" }
  ]
}
```

| Parameter | Required | Description |
| --- | --- | --- |
| `messages` | Yes | A JSON **string** containing the conversation array. Anything else answers `400`. |
| `apiKey` | Yes | Your OpenAI API key. |
| `model` | Yes | The OpenAI model name. |
| `tools` | No | A JSON string containing a tools array for function calling. |

The response is a `Parameters` resource. `content` carries the answer; `tool_calls` carries any tool calls as a JSON string. Send `Accept: text/event-stream` to receive the answer as a stream.

## Turn it on [#turn-it-on]

```bash
curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/features' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"features":["bots","cron","email","transaction-bundles","websocket-subscriptions","ai"]}'
```

Start from the list `GET /v1/projects/me/features` returns, and add `ai` to it.

## What callers see [#what-callers-see]

| Condition | Status | Message |
| --- | --- | --- |
| Feature is off | `403` | `Forbidden` |
| A required parameter is missing | `400` | For example `Expected 1 value(s) for input parameter messages, but 0 provided` |
| `messages` is not an array | `400` | `Messages must be an array` |

## Gotchas [#gotchas]

- **Your content leaves Ovok.** The conversation you send, and the key you send it with, go to OpenAI. Do not send patient-identifying data unless your own agreement with OpenAI allows it. OpenAI processes it outside Ovok's infrastructure.
- **You bring and pay for the key.** Ovok does not supply a model key; OpenAI bills usage to the owner of the key.
- **The key travels in the request body.** Do not call `$ai` from a browser or a mobile app that ships with the key; call it from your server.
- **`messages` is a string, not an array.** Wrap the JSON array in a string; an array that is not valid JSON, or a value that is not an array, answers `400`.
- **Streaming needs a client that reads server-sent events.** Test it through your own network path before you depend on it.
- **This is separate from Ovok's own AI routes.** The feature does not gate other AI features Ovok may offer.
- **Projects do not inherit it.** Turn it on in each project that needs it.

## Related [#related]

- [Settings and features](/settings-and-features#project-features)
- [aws-textract](/settings-and-features/features/aws-textract)
