Citations | Council developer console

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.

Add a citations object to a chat completion. Council searches the knowledge scopes you choose using the last user message, gives the model the passages it finds as numbered sources, and asks it to cite them as [1], [2]. The response lists each source in a citations array.

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."}],
    extra_body={
        "citations": {"enabled": True, "sources": ["public_kb"], "top_k": 3},
    },
)

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." }],
  citations: { enabled: true, sources: ["public_kb"], top_k: 3 },
});

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." }],
    "citations": { "enabled": true, "sources": ["public_kb"], "top_k": 3 }
  }'

The citations object

Citation parameters
Parameter	Description
enabledboolean	Turn retrieval on for this request. Default `false`.
requiredboolean	When `true`, the request fails if retrieval cannot run: `503 retrieval_unavailable` when the retrieval service is down or slow, `400 invalid_request` when it rejects the search or the request has no user message. When `false`, those retrieval failures give an answer without citations; non streaming responses also carry a `warnings` entry. Scope problems (an empty `sources` list, an unknown scope, or one the key does not allow) fail the request either way. A search that runs and finds nothing is not a failure. Default `false`.
sourcesarray of strings	Knowledge scopes to search: `public_kb`, `customer_kb`, `personal_kb`. Leave it out to search the scopes your key allows (public plus customer, or public plus personal).
top_kinteger	Passages to retrieve, from 1 to 50. Default `8`.
source_typesarray of strings	Only retrieve passages from these source types.
min_scorenumber	Minimum similarity from 0 to 1 for a passage to be used. Default `0.3`.

The response

Each citation describes one retrieved source: the number the model can cite it by, the knowledge scope it came from, identifiers for the chunk and document, a title, the similarity score when the search reports one, and a short excerpt. The model is asked to cite only the sources it uses, so an answer may not cite every listed source.

Response

{
  "object": "chat.completion",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "First line options include thiazide diuretics and ACE inhibitors [1]..."
    }
  }],
  "citations": [{
    "id": 1,
    "scope": "public_kb",
    "chunk_id": "...",
    "document_id": "...",
    "title": "Clinical practice guideline",
    "source_type": "guideline",
    "similarity": 0.82,
    "excerpt": "...",
    "metadata": {}
  }]
}

Sample response for illustration. Not medical advice.

When retrieval is unavailable

With required left false, the model still answers, without citations. Non streaming responses carry a warning whose code names the retrieval error:

Warning

"warnings": [{
  "code": "retrieval_unavailable",
  "message": "Citation retrieval was unavailable; response generated without citations"
}]

Pricing

Non streaming requests are billed at grounded chat rates when retrieval runs, even if it finds nothing, and at core chat rates when optional retrieval could not run. Streaming requests with citations enabled always use grounded chat rates. When citations are enabled, knowledge scopes the key does not allow fail with 403 insufficient_scope, whether or not required is set. The Billing page lists the current rates.

Good to know

The model is told to treat retrieved passages as reference data and not to follow instructions inside them. Treat model output that quotes a source with the same care as any other output.
Citations support the work of qualified professionals. Check sources before relying on an answer.