diagnos

REST API

GET /v1/patients/{patient_id}

Get one patient

Published from commit 4eb9d27
GET /v1/patients/{patient_id}

Fetches and decrypts one patient: the newest content, or version_id.

Path parameters #

  • patient_id string required

    The patient's document id.

Query parameters #

  • version_id string

    Read this committed version instead of the newest content.

  • include_draft boolean

    Read the web editor's draft when it is newer than the latest version (the web app's rule).

Responses #

  • 200 Successful Response

    • index object required

      What the vault knows about a patient/exam/template (`docs/PROTOCOL.md §8`): keys, streams, clear metadata. Every field here is something the vault itself reads to route and authorize. The clinical content never appears on this model: it lives in the sealed object of each version, and a short sealed summary (name, title) lives in `encrypted_index`, which only a DEK holder opens. Exactly one `security_group_id` per document: sharing a patient with another team means copying it, never sharing its key.

    • version_id object
    • draft_rev object
    • record object required

      The `data` stream of a patient (`PatientData` in the web app) — everything here is sealed before upload. `birth_date` accepts a `date` or an aware `datetime` and is stored the way the web app stores it, as a UTC ISO 8601 instant. Set `Settings.time_precision` to truncate it to the workspace's anonymization precision before sealing, like the web app does.

    • summary object

  • 400 The vault refused the request as invalid.

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 401 No client certificate, or the SDK session was rejected or expired (`session_expired`).

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 402 The workspace has no credit for this.

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 403 CN not allowed, permission denied, or no key for the data's security group (`group_key_unavailable`).

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 404 Not found — also a node read under a group it does not belong to.

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 409 A pending or newer version, a replay, or an upload that never reached storage.

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 422 The body or query failed validation (`invalid_request`).

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 429 Rate limited, after the SDK's own backoff gave up.

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 500 An envelope did not open (`crypto_error`, no detail on purpose).

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

  • 502 The vault failed, or answered outside the protocol (`protocol_error`).

    • error object required

      The body of every non-2xx response: what went wrong, for a program and for a person.

curl --cert client.crt --key client.key \
  -X GET "https://api.imgexam.com/v1/patients/<patient_id>?version_id=<string>&include_draft=<boolean>" \
  -H "Content-Type: application/json"
 
{
  "index": {
    "document_id": "string",
    "workspace_id": "string",
    "resource": "patients",
    "security_group_id": "string",
    "encrypted_keys": {},
    "encrypted_index": {},
    "streams": {},
    "meta": {},
    "created_at": "string",
    "created_by": "string",
    "updated_at": "string",
    "updated_by": {},
    "is_archived": false,
    "is_deleted": false
  },
  "version_id": {},
  "draft_rev": {},
  "record": {
    "legal_name": "string",
    "display_name": "string",
    "identifiers": {},
    "external_id": {},
    "birth_date": {},
    "biological_sex": {},
    "gender_identity": {},
    "race_identity": {},
    "email": {},
    "phone": {},
    "address": {},
    "internal_notes": {},
    "custom_attributes": {}
  },
  "summary": {}
}