API reference

The neolife API is a plain REST surface over JSON. It's fully described by an OpenAPI 3.1 document you can feed to your own tooling.

• Base URL: https://api.neolife.health
• Interactive reference: /docs
• Machine-readable spec: /openapi.json — import it straight into Postman, Insomnia, or an SDK generator to get a ready-to-run request collection. The spec is the public surface only; PHI-touching paths are flagged x-neolife-phi.

Versioning#

The current unversioned paths are v1. You can pin the stable, dated prefix /v1/* — /v1/orders and /orders resolve to the same handler. Every response carries a dated Neolife-Version header so you always know what you're talking to.

curl https://api.neolife.health/v1/orders \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Core resources#

Each resource has its own reference page with every endpoint, parameter, and response shape:

Resource	What it is
Orders	Create, approve, submit, and track fulfillment orders.
Intake	Compliance questionnaires and provider approval.
Patients	Patient records behind the PHI boundary.
Catalog	Your formulary — drugs, strengths, protocols.
Pharmacies	Pharmacy connections and routing.
API keys	Machine API keys.
Webhook endpoints	Webhook endpoint management.
Events	The durable, PHI-free event log — pull + replay.
Usage	Metered API usage for your tenant.

The full request/response schema for every path lives in /openapi.json.

Idempotency#

Every mutation accepts an Idempotency-Key (a UUID) so retries never double-act. See Idempotency.

Errors {#errors}#

Errors return a JSON body with a stable code and a human-readable message, plus a request id you can quote in support:

{
  "error": {
    "code": "order_not_approved",
    "message": "Refusing to submit: order has not been approved by a licensed provider."
  }
}

Status	Meaning
400	Malformed request.
401	Missing or invalid API key.
403	Authenticated but not permitted (scope, or an unapproved clinical action).
404	No such resource on your tenant.
409	Idempotency conflict (same key, different body) or a state conflict.
422	Well-formed but semantically invalid.
429	Rate limited — back off and retry.

Every response includes an X-Request-Id (req_…) — include it when contacting support.

Rate limits#

The API is rate limited per key. On a 429, honor the backoff and retry with the same Idempotency-Key so the retry is safe.