API conventions

These conventions apply across OpenHI’s HTTP API. Exact hostnames and release notes ship with early access. The shape below is what you design against.

Authentication

Send a bearer token on every request:

Authorization: Bearer <access_token>

Unauthenticated calls are rejected before application logic runs.

Tenant and workspace scope

Active tenant and workspace are resolved from the token, not from path segments.

GET /Patient/abc-1

means that resource in the caller’s current tenant and workspace. Switching context requires a new scoped session, not a different base path.

Content type

JSON request and response bodies. Prefer an explicit JSON content type on writes. Error payloads use a structured outcome document (a machine-readable issue list) rather than free-form HTML errors.

Reads, writes, lists

Most resources follow familiar REST habits:

• GET /{Type}/{id}: read
• POST /{Type}: create
• PUT /{Type}/{id}: update
• DELETE /{Type}/{id}: delete
• GET /{Type}: list / search (parameters expanding over time)

Version history exists on data-plane resources where applicable (_history style reads). Details land in the fuller API reference as it ships.

Batch

You can submit a batch of independent operations in a single request (bundle-style). Entries are independent: one failure does not automatically roll back the others. Prefer batch for latency. Prefer parallel clients when you need isolation.

What this page is not

This is not a complete resource catalog. See API status for what is early vs next, and Standards & models for ontology and terminology.