Chat completions

The core endpoint: send messages, get a completion.

POST/v1/chat/completions

Creates a model response for a conversation. Requires the chat:completions scope.

Do not send protected health information yet.A Business Associate Agreement (BAA) with Health Council must be signed before any protected health information reaches the API. Use synthetic or deidentified data until then.

Request body

Chat completion parameters
Parameter	Description
modelstring	Model to use. It must be allowed for the key. Leave it out to use the default model.
messagesarrayRequired	The conversation so far. Each message has a `role` (`system`, `user`, `assistant`, or `tool`), `content` as text or content parts, and an optional `name`.
temperaturenumber	Sampling temperature from 0 to 2.
max_tokensinteger	Most tokens to generate, up to 4,096. The balance check before the request assumes this many output tokens.
streamboolean	Send the answer as server sent events. See Streaming. Default `false`.
citationsobject	Ground the answer in a knowledge base. See Citations.

Other OpenAI parameters, such as top_p and stop, are passed to the model unchanged.

Returns

A chat.completion object in the OpenAI shape, with usage when the model reports it. Grounded requests add a citations array when retrieval found sources, and a warnings array appears when optional retrieval could not run.

Errors

400 invalid_request: the body failed validation, the model is not allowed, or max_tokens is above 4,096.
402 payment_required: the balance is empty or cannot cover max_tokens.
429 rate_limited: the key reached its per minute limit or monthly token cap.
502 model_error and 504 model_timeout: the model did not answer; retry with backoff.

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://developer.council.health/v1",
    api_key=os.environ["COUNCIL_API_KEY"],
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",  # GET /v1/models lists yours
    messages=[{"role": "user", "content": "Summarize first line treatment for hypertension."}],
)

print(response.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://developer.council.health/v1",
  apiKey: process.env.COUNCIL_API_KEY,
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID", // GET /v1/models lists yours
  messages: [{ role: "user", content: "Summarize first line treatment for hypertension." }],
});

console.log(response.choices[0].message.content);

curl

curl https://developer.council.health/v1/chat/completions \
  -H "Authorization: Bearer $COUNCIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{ "role": "user", "content": "Summarize first line treatment for hypertension." }]
  }'

Response

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "model": "YOUR_MODEL_ID",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 18, "completion_tokens": 96, "total_tokens": 114 }
}

Sample response for illustration. Not medical advice.