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.

POSThttps://api.zeteo.health/v1/conversations/:id

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"]
    }
  }'

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"
}
FieldTypeDescription
answerstringThe response text, with numbered citation markers.
citationsarrayOne entry per citation marker, with source name and URL where available.
trust_scorenumber0–1 confidence score. See Trust Score below.
hipaa_compliantbooleanAlways true for production responses; included for auditing.
conversation_idstringEchoes 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.

RangeMeaning
0.85 – 1.0Strong grounding in vetted sources and provided context.
0.6 – 0.85Reasonable grounding; consider showing a caveat in your UI.
Below 0.6Limited grounding; we recommend routing to a human or declining to answer.

Errors

StatusMeaning
401Missing or invalid API key.
403Key valid but not authorized for this conversation or context scope.
422Request body missing required fields, or context malformed.
429Rate limit exceeded. See Rate limits below.
500Something 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.

Frequently asked questions

Request API access, sign a BAA, and we'll issue sandbox and production keys.

Yes, zk_test_ keys hit a sandbox with synthetic data, no real patient context required.

Yes, see Zeteo AI for layering your own protocols and content on top of the foundation knowledge base.

Python, JavaScript, and TypeScript SDKs are available; other languages can call the REST endpoint directly.

Ready to integrate?

Get sandbox access and start sending real requests today.

Request API access