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

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

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:

{
  "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

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

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

• 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

• Settings and features
• aws-textract