API Overview

This page covers the technical foundations every integration builds on: how the platform is structured, which environments exist, and the conventions all requests and responses follow. For what the API does and how a consultation works, start with the Introduction.

Architecture at a glance

  Your backend / UI
        │  HTTPS, JSON (snake_case)
        ▼
  API gateway (/api/v1)           ← authentication, legal consent, rate limiting
        │
        ▼
  Conversation engine             ← conversation state machine, question logic
        │
        ▼
  Medical NLU, terminology, and diagnostic services

Two properties of this design matter to you as an integrator:

• The server is authoritative and stateful per session. Conversation state is keyed to your access token and stored server-side. You never send state — only the answer to the current question. This also means requests must be sequential within one conversation: answer the question you were last given.
• The client is schema-driven. Questions arrive with a type, display messages, choices, and constraints (min/max selections). A well-built client renders from these fields generically and needs no per-question logic.

Environments and base URLs

You will be issued three credentials per environment by Healthily:

• partner_id — your partner identifier
• secret — the partner secret (used only at login)
• api_key — sent as the x-api-key header on every request

Treat all three as server-side secrets (see Authentication).

Wire conventions

• Content type: application/json for all request and response bodies.
• Field naming: snake_case throughout (initial_query, step_back_possible).
• Empty fields are omitted: responses exclude null/empty fields (NON_EMPTY serialization). Always code defensively — check for presence before reading nested objects like question, report, or choices.
• Unknown fields are ignored by the server, and new fields may be added to responses over time; your parser must tolerate unknown fields too.
• Medical concept identifiers: choices and symptoms are identified by UMLS-style CUIs (e.g. C0041105). Treat these as opaque IDs — echo them back in answers, never parse or translate them.
• Language: an optional X-Language header may be sent on login (default en-US). Only languages enabled for your partner account are accepted; the conversation language is locked into the session token.

Standard headers

Versioning

The public, supported surface is v1 (/api/v1/...). Older /v3 and /v4 partner APIs exist for legacy integrations and are not covered here; do not build new integrations against them.