Zeteo Gateway — API Reference
Add clinically grounded AI to your product with one endpoint.
Structured, cited, confidence-scored responses. HIPAA-compliant infrastructure. This page documents authentication, the conversational endpoint, and the response schema.
Authentication
Every request is authenticated with an API key, issued after your organization signs a Business Associate Agreement (BAA). Pass it as a bearer token in the Authorization header.
Authorization: Bearer zk_live_••••••••••••••••Keys are environment-scoped. Use a zk_test_ key against the sandbox while you integrate, and a zk_live_ key once you're ready to send real patient context.
The conversational endpoint
One endpoint handles every conversation. Send a message with whatever context your product has, get back a structured, cited answer.
Request
The :id in the URL is a conversation ID your product generates, so follow-up messages in the same thread carry context forward. The body carries the message and any structured context you have.
curl -X POST https://api.zeteo.health/v1/conversations/conv_123 \
-H "Authorization: Bearer $ZETEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Is it safe to take ibuprofen with lisinopril?",
"context": {
"patient_id": "pt_789",
"medications": ["lisinopril"]
}
}'# pip install zeteo from zeteo import Zeteo client = Zeteo(api_key="ZETEO_API_KEY") response = client.conversations.send( id="conv_123", message="Is it safe to take ibuprofen with lisinopril?", context={"patient_id": "pt_789", "medications": ["lisinopril"]}, ) print(response.answer, response.trust_score)
// npm install @zeteo/sdk import { Zeteo } from "@zeteo/sdk"; const client = new Zeteo({ apiKey: process.env.ZETEO_API_KEY }); const response = await client.conversations.send("conv_123", { message: "Is it safe to take ibuprofen with lisinopril?", context: { patientId: "pt_789", medications: ["lisinopril"] }, }); console.log(response.answer, response.trustScore);
// npm install @zeteo/sdk import { Zeteo, type ConversationResponse } from "@zeteo/sdk"; const client = new Zeteo({ apiKey: process.env.ZETEO_API_KEY! }); const response: ConversationResponse = await client.conversations.send("conv_123", { message: "Is it safe to take ibuprofen with lisinopril?", context: { patientId: "pt_789", medications: ["lisinopril"] }, });
Response schema
Every response is structured JSON with in-text citations back to the source, not an opaque block of text.
{
"answer": "Caution is advised. NSAIDs like ibuprofen can reduce the effectiveness of ACE inhibitors like lisinopril [1].",
"citations": [
{ "id": 1, "source": "Zeteo Foundation Knowledge Base", "url": "https://kb.zeteo.health/..." }
],
"trust_score": 0.91,
"hipaa_compliant": true,
"conversation_id": "conv_123"
}| Field | Type | Description |
|---|---|---|
| answer | string | The response text, with numbered citation markers. |
| citations | array | One entry per citation marker, with source name and URL where available. |
| trust_score | number | 0–1 confidence score. See Trust Score below. |
| hipaa_compliant | boolean | Always true for production responses; included for auditing. |
| conversation_id | string | Echoes the conversation ID for correlating follow-ups. |
Trust Score
Every response includes a trust_score between 0 and 1, reflecting how well the answer is grounded in vetted sources and the context you provided. We recommend surfacing this to your users rather than hiding it, it's the core of what differentiates a grounded answer from a generic model response.
| Range | Meaning |
|---|---|
| 0.85 – 1.0 | Strong grounding in vetted sources and provided context. |
| 0.6 – 0.85 | Reasonable grounding; consider showing a caveat in your UI. |
| Below 0.6 | Limited grounding; we recommend routing to a human or declining to answer. |
Errors
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key. |
| 403 | Key valid but not authorized for this conversation or context scope. |
| 422 | Request body missing required fields, or context malformed. |
| 429 | Rate limit exceeded. See Rate limits below. |
| 500 | Something went wrong on our end. Safe to retry with backoff. |
Rate limits
Rate limits are scoped per API key and set during onboarding based on your expected volume. Every response includes standard X-RateLimit-Limit and X-RateLimit-Remaining headers so you can back off proactively.