API ReferenceVersion 2.0 — 202614 min read

Platform API Overview

Endpoints the Aimedis Platforms Offer Today

Endpoints of Aimedis Care (patient-granted FHIR R4), Aimedis Pro (practice software: FHIR R4 and HL7 v2.5.1), Aimedis Rehab and Aimedis Decision, with credentials, parameters, examples, errors and limits.

Sections

Introduction
Getting Access
Aimedis Care Record Access (FHIR R4)
FHIR R4 Resources
Interfaces by Product
Cross-Platform Integration Patterns

Introduction

This reference lists the endpoints the Aimedis care platforms offer other systems today: Aimedis Care's patient-granted FHIR R4 read access, Aimedis Pro's practice-software interface, and the downloads and uploads of Rehab and Decision. The Aimedis Wiki API has its own guide.

What you can build

Read a patient's shared record with the patient's AIM-ID and PIN
Show a practice's Aimedis bookings in its practice software
Block busy times in Aimedis Pro from the practice's own calendar
Send lab and device results to a patient's Aimedis Care inbox (HL7 ORU^R01)
Ground your own AI in reviewed evidence with the Wiki API
Look up and validate ICD-10 and ICD-11 codes with the Wiki terminology server

Platform provides access to

Read-only FHIR R4 (4.0.1) access to the categories a patient shares, with a token valid for 15 minutes per PIN exchange
A FHIR R4 practice interface for Practitioner, Schedule and Appointment, plus HL7 v2.5.1 SIU and ORU messages over HTTPS
Patient-created shares: seven categories, a PIN of 6 to 12 digits, from 1 hour to 90 days or until revoked
An append-only audit log of record access in Aimedis Care, with entries linked by SHA-256 hashes

Getting Access

There is no single Aimedis API key and no partner program that issues one. Each interface takes its own credential, issued by the owner of the data.

Choose the Interface
Aimedis Care record access, Aimedis Pro's practice-software interface or the Wiki API: each section below says who may use it.
Get the Credential
The patient gives you an AIM-ID and PIN; a practice administrator creates an apx_ credential in Aimedis Pro; a Wiki administrator issues an awr_ key.
Build and Test
Build against the endpoints below and test with fictional data; there is no sandbox.
Go Live
Work through the go-live checklist in Access and Credentials (Section 09). Revoke a credential as soon as it may have leaked.

Authenticated requestHTTP

GET /api/interop/fhir/r4/Appointment?date=ge2026-11-10&date=lt2026-11-17
Host: pro.aimedis.com
Authorization: Bearer apx_…
Accept: application/fhir+json

There is no self-service sign-up, sandbox or published SDK, and no date is set for one. See Section 08.

Base URL https://care.aimedis.com. The patient creates a share in Aimedis Care (categories, duration, single or multiple use, PIN). Your server exchanges the patient's AIM-ID and PIN for a token and reads the shared data as FHIR R4. Shares cannot be created, listed or revoked through the API.

POST/api/access/redeem

Exchange the patient's AIM-ID (or account UUID) and PIN for a Bearer token valid for 15 minutes and limited to the shared categories. JSON body of at most 8 KiB; no record data is returned. Every refused PIN gets the same 401. Limits: 5 attempts per 15 minutes per client address and 10 per patient; 5 wrong PINs lock out the requester, 10 lock the share for everyone, until 1 hour after the first wrong PIN (429 with Retry-After).

Request headersHTTP

POST /api/access/redeem
Host: care.aimedis.com
Content-Type: application/json

Request bodyJSON

{
  "patientId": "AIM-123456ABC",
  "pin": "<the PIN the patient gave you>"
}

ResponseJSON

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9…",
  "token_type": "Bearer",
  "scope": ["vitals", "diagnoses", "medications"],
  "expires_in": 900
}

Example error bodyJSON

HTTP 401
{ "error": "Invalid patient ID or PIN" }

GET/api/access/records

Everything the share covers as one FHIR R4 collection Bundle: Patient (profile), Observation (vitals, laboratory), Condition and AllergyIntolerance (diagnoses), MedicationStatement (medications) and DocumentReference (documents, diary). No query parameters.

RequestHTTP

GET /api/access/records
Host: care.aimedis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
Accept: application/fhir+json

Success responseJSON

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    { "resource": { "resourceType": "Patient", "id": "…" } },
    { "resource": { "resourceType": "Observation", "id": "…", … } },
    { "resource": { "resourceType": "Condition", "id": "…", … } }
  ]
}

GET/api/fhir/{type}

Search one resource type (Patient, Observation, Condition, MedicationStatement, AllergyIntolerance or DocumentReference) with _id, _count (1–200, default 100) and _offset. The answer is a searchset Bundle with total and, while more remain, a next link. GET /api/fhir/{type}/{id} reads one resource; GET /api/fhir/metadata needs no token.

RequestHTTP

GET /api/fhir/Observation?_count=2
Host: care.aimedis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

Example response bodyJSON

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 14,
  "link": [
    { "relation": "self", "url": "https://care.aimedis.com/api/fhir/Observation?_count=2" },
    { "relation": "next", "url": "https://care.aimedis.com/api/fhir/Observation?_count=2&_offset=2" }
  ],
  "entry": [ … ]
}

Example error bodyJSON

HTTP 401
{
  "resourceType": "OperationOutcome",
  "issue": [
    { "severity": "error", "code": "login", "diagnostics": "A valid active access grant is required" }
  ]
}

Other OperationOutcome issue codes:

expiredforbiddennot-supportedvaluenot-foundtransient

401 login or expired: the token is missing, invalid or expired, or the patient revoked the share. 403 forbidden: the category was not shared. 400 not-supported or value: an unsupported, repeated or invalid parameter. 404 not-found: no such resource. 503 transient: retry later.

GET/api/fhir/Patient/{id}/$summary

A patient summary document Bundle in the International Patient Summary structure: a Composition (LOINC 60591-5) with medications, allergies, problems, results and vital signs; not validated against the IPS profiles. Sections outside the shared categories are present but empty (withheld). The id must be the token's patient.

RequestHTTP

GET /api/fhir/Patient/{id}/$summary
Host: care.aimedis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…

Example response bodyJSON

{
  "resourceType": "Bundle",
  "type": "document",
  "entry": [
    { "resource": {
        "resourceType": "Composition",
        "status": "final",
        "type": { "coding": [ { "system": "http://loinc.org", "code": "60591-5" } ] },
        "section": [ … ]
    } },
    { "resource": { "resourceType": "Patient", … } },
    …
  ]
}

Mechanics

PIN mechanics
The patient chooses a PIN of 6 to 12 digits (no repeated digits or straight sequences) when creating the share. Aimedis Care stores only a salted scrypt hash and never shows the PIN again.
Lifetimes
The PIN is valid as long as its share: 1, 8 or 24 hours, 7, 30 or 90 days, or until revoked; a single-use PIN works once. Each exchange gives a token for 15 minutes, and a revoked share stops the token at the next read.
Categories
vitals, diagnoses (with allergies), medications, laboratory, documents, diary and profile. There are no separate sensitive categories: the patient decides per category.
No break-glass
Aimedis Care has no emergency override for professionals. The patient's emergency card (a QR link plus a 6-digit PIN, valid for 8 hours) shows profile, diagnoses, allergies and medications in a browser; it is not an interface for other systems.
Hash-chained audit log
Every PIN exchange and every read is written to Aimedis Care's append-only audit log, whose entries are linked by SHA-256 hashes. The patient sees them as access history and is alerted when a share is used (at most once per share in 6 hours).

Standards

HL7 FHIR R4 (4.0.1)
HL7 v2.5.1
GDT 2.1 / 3.5
International Patient Summary (structure)

FHIR R4 Resources

All FHIR endpoints of the care platforms use JSON (application/fhir+json) and FHIR 4.0.1. None claims conformance to a published profile, and none implements SMART on FHIR, history or transactions.

Resource types by category and interface

profile: Patient
vitals: Observation (vital-signs)
laboratory: Observation (laboratory)
diagnoses: Condition, AllergyIntolerance
medications: MedicationStatement
documents: DocumentReference
diary: DocumentReference (GET /api/access/records only)
patient summary: Bundle (document): Composition, Patient, MedicationStatement, AllergyIntolerance, Condition, Observation
Pro practice interface: Practitioner, Schedule, Appointment

Diagnoses carry an ICD-10 coding only when the Aimedis Wiki terminology server confirms the code (WHO ICD-10 first, then ICD-10-GM); otherwise the diagnosis is sent as text. A stored ICD-11 code keeps its ICD-11 coding.

Interfaces by Product

The interfaces of Aimedis Pro, Aimedis Rehab and Aimedis Decision. Only Pro's practice-software endpoints are for unattended server-to-server use; the Rehab and Decision endpoints serve signed-in patients and clinicians. Aimedis Support offers none.

Aimedis Pro — Practice Software Interface

Base URL https://pro.aimedis.com. A practice administrator creates the credential in Aimedis Pro (Practice → Practice software) with the scopes appointments:read, appointments:write and results:write. It is shown once (apx_ followed by 43 characters), has no expiry and is revoked in Pro. Limits: 600 requests per 10 minutes per credential and bodies up to 6,000,000 bytes. Every call is written to Aimedis Care's audit log before data is read or written.

GET/api/interop/fhir/r4/Appointment

Search the practice's Aimedis bookings (scope appointments:read). Parameters: date (repeatable; prefixes ge, gt, le, lt, eq; a date alone means the whole day in the practice's time zone), practitioner, _count (default 50, at most 100) and _offset (at most 10,000). The patient appears only by display name: no ID, contact details or reason.

Response (excerpt)JSON

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "link": [ { "relation": "self", "url": "https://pro.aimedis.com/api/interop/fhir/r4/Appointment?date=ge2026-11-10" } ],
  "entry": [ {
    "fullUrl": "https://pro.aimedis.com/api/interop/fhir/r4/Appointment/…",
    "search": { "mode": "match" },
    "resource": {
      "resourceType": "Appointment",
      "id": "…",
      "status": "booked",
      "start": "2026-11-12T08:30:00Z",
      "end": "2026-11-12T08:50:00Z",
      "minutesDuration": 20,
      "participant": [
        { "actor": { "reference": "Practitioner/…", "display": "Dr. Ada Example" }, "status": "accepted" },
        { "actor": { "type": "Patient", "display": "Mira Sample" }, "status": "accepted" }
      ]
    }
  } ]
}

GET/api/interop/fhir/r4/Practitioner

The practice's practitioners, and at …/Schedule one Schedule per practitioner (active means bookable online; search by actor). GET …/metadata returns the CapabilityStatement without a credential. Free slots are not offered.

POST/api/interop/fhir/r4/Appointment

Block a practitioner's busy time from your calendar (scope appointments:write). The body is a FHIR Appointment with your identifier (the idempotency key), one Practitioner participant, start and end on the same day and a busy status. 201 with Location …/Appointment/blk-{id}; a repeated identifier answers 200. PUT …/Appointment/blk-{id} moves your block and DELETE removes it (204); bookings made in Aimedis cannot be changed (405).

Request BodyJSON

{
  "resourceType": "Appointment",
  "identifier": [ { "value": "pvs-block-20261112-001" } ],
  "status": "booked",
  "start": "2026-11-12T12:00:00+01:00",
  "end": "2026-11-12T13:00:00+01:00",
  "participant": [ { "actor": { "reference": "Practitioner/…" }, "status": "accepted" } ]
}

POST/api/interop/hl7v2

One HL7 v2 message per request (Content-Type text/plain or x-application/hl7-v2+er7). SIU S12 creates, S13 and S14 move, S15 and S17 remove a busy block (scope appointments:write). ORU^R01 results for a patient whose PID-3 carries the AIM-ID and who has shared the record with the practice go to the patient's Aimedis Care inbox, where the patient accepts or dismisses them (scope results:write). The answer is always an ACK (MSA AA, AE or AR).

Request BodyHL7

POST /api/interop/hl7v2
Host: pro.aimedis.com
Authorization: Bearer apx_…
Content-Type: x-application/hl7-v2+er7

MSH|^~\&|…|…|…|…|…||SIU^S12^SIU_S12|MSG00001|P|2.5.1
SCH|…
AIP|…   (AIP-3: the practitioner)

→ 200 OK (x-application/hl7-v2+er7)
MSH|^~\&|…||ACK^S12^ACK|…|P|2.5.1
MSA|AA|MSG00001

GET/api/interop/hl7v2/siu?since={instant}

SIU messages (HL7 v2.5.1) for the practice's bookings changed since an ISO 8601 instant with its offset, or since the next value of the previous answer: S12 new, S14 changed, S15 cancelled. At most 200 per call, as JSON { messages, next }; patient name only, no patient identifier (scope appointments:read).

ResponseJSON

{
  "messages": [ "MSH|…|AIMEDIS PRO|…|SIU^S12^SIU_S12|…|P|2.5.1 …" ],
  "next": "2026-11-10T09:30:00.000Z~…"
}

GET/api/patients/{id}/export?format=gdt35|gdt21|hl7|fhir

A signed-in professional downloads the part of a shared record they may see, for import into practice software: format=gdt35 (GDT 3.5, record type 6310), gdt21 (GDT 2.1), hl7 (ORU^R01, v2.5.1) or fhir (FHIR R4 collection Bundle). GDT and HL7 carry results and notes only.

Aimedis Rehab — Neurorehabilitation

Base URL https://rehab.aimedis.com. These endpoints serve the signed-in patient or a clinician the patient granted access. They authenticate with the person's own session token (Authorization: Bearer), not with a key for other systems, and send nothing anywhere.

GET/api/rehab/patients/{id}/fhir-export

A FHIR R4 collection Bundle of the patient's rehab record: Patient, Condition, EpisodeOfCare, Encounter, Observation, Goal, CarePlan, Task, Procedure, Consent, DocumentReference and Provenance. Vital signs and scale totals carry LOINC codes where one exists (Barthel 96761-2, GCS 9269-2, MoCA 72172-0, NIHSS 72089-6). 5 exports per 10 minutes; each export is audited before release.

GET/api/rehab/patients/{id}/discharge-report?episode={id}

The discharge summary of one episode as a FHIR R4 document Bundle: a Composition (LOINC 18842-5) with Patient, Organization, Practitioner, EpisodeOfCare, Condition, Observation (assessment totals and ICF-coded functioning), QuestionnaireResponse (Barthel, FIM), Goal and CarePlan.

POST/api/rehab/referrals/import

A signed-in clinician uploads one referral as multipart/form-data (field file, at most 6,000,000 bytes): a FHIR R4 ServiceRequest, or a Bundle with ServiceRequest, Patient, Condition and DocumentReference entries. HL7 v2 and GDT files are refused (415). The referral waits until the clinician accepts or declines it; 20 uploads per 10 minutes.

POST/api/wearables/apple/import

The patient's own iPhone export app (for example Health Auto Export) sends Apple Health readings with an import key (Authorization: Bearer ahk_…) that the patient creates in the app; at most 1,000 readings and 2 MiB per request. Aimedis Care offers the same endpoint.

Aimedis Decision — Clinical Decision Support

Base URL https://decision.aimedis.com. Aimedis Decision's AI triage suggestion (care level, urgency, specialty, ICD-10 codes, red flags and the model's self-reported confidence) is shown only to the physician of the case, inside the app: non-binding decision support, and the licensed clinician decides. Finished care plans and letters reach the patient's Aimedis Care inbox through a signed connection between Aimedis apps, where the patient accepts or dismisses them.

GET/api/interop/care-plan/{consultationId}/fhir

The newest care plan of a consultation as a FHIR R4 document Bundle, for the consultation's patient or physician (signed in): a Composition (LOINC 18776-5), Patient, Practitioner, Condition (ICD-10), CarePlan, ServiceRequest (referral, rehabilitation recommendation) and a DocumentReference holding the care-plan PDF. Each download is audited.

Aimedis Support — No Interface for Other Systems

The help center, requests, surveys, NPS, the community board and the AVA support assistant are used only through Support's own pages and its help widget. The widget runs only inside Aimedis's own sites (an allow-list of origins), so other websites cannot embed it.

Cross-Platform Integration Patterns

Between Aimedis apps, data moves through the shared family database (Booking, Pro, Onboard, Connect) or through signed server-to-server requests (partner-hmac-v1). Outside systems cannot use either path.

Booking → Pro → Practice Software
Bookings made in Aimedis Booking appear in Aimedis Pro's practice schedule. Practice software reads them through Pro's FHIR Appointment search or HL7 SIU feed and can block busy times there (Section 05).
Aimedis Onboard Intake → Pro
Aimedis Pro opens an intake with the patient's AIM-ID and intake PIN, or through a visit grant the patient gives for one appointment (at most 3 days). With an account, the answers are also sent to Aimedis Care, where the patient confirms them item by item.
Pro Registry → Connect Verification
Professional status comes from Aimedis Pro. Connect treats a clinician registered in Pro (not a Pro administrator account) as verified and lets that professional open a record a patient shares in a chat; Aimedis Care checks the professional status again before it issues a token.

AVA Integration

AVA is the assistant inside each Aimedis app. Its endpoints accept only that app's own signed-in pages; there is no AVA API for other systems. To ground your own model in the evidence AVA uses (Aimedis Wiki, Aimedis RAG, PubMed, Public Medical Library), call the Wiki API's research endpoint with a Wiki API key.

Where AVA offers clinical guidance, such as Aimedis Decision's triage suggestion for the physician, it is non-binding decision support: the licensed clinician always decides.

Not Offered Today

None of these is available today. Only the interface gateway is planned, and only for a concrete partner project; no date is set.

Webhooks
Not offered. Aimedis apps notify each other only through signed server-to-server requests that outside systems cannot use.
Self-Service Credentials
Not offered. Credentials come from a Wiki administrator (awr_ keys), a practice administrator in Aimedis Pro (apx_ credentials) or the patient (a PIN share).
Client Libraries / SDKs
Not published. The Wiki team can provide TypeScript and Python sample clients for the Wiki API; there are none for the care platforms.
Sandbox Environment
Not offered: there is no public test environment with synthetic data.
Interface Gateway
Planned only for a concrete partner project, not built: a separate gateway, for example for HL7 v2 over MLLP and SMART Backend Services.

Start with the credential the owner of the data gives you: a patient's share, a practice's credential or a Wiki API key. For anything this reference does not cover, contact Aimedis.

Introduction

What you can build

Platform provides access to

Getting Access

Choose the Interface

Get the Credential

Build and Test

Go Live

Aimedis Care Record Access (FHIR R4)

Mechanics

PIN mechanics

Lifetimes

Categories

No break-glass

Hash-chained audit log

Standards

FHIR R4 Resources

Resource types by category and interface

Interfaces by Product

Aimedis Pro — Practice Software Interface

Aimedis Rehab — Neurorehabilitation

Aimedis Decision — Clinical Decision Support

Aimedis Support — No Interface for Other Systems

Cross-Platform Integration Patterns

Booking → Pro → Practice Software

Aimedis Onboard Intake → Pro

Pro Registry → Connect Verification

AVA Integration

Not Offered Today

Webhooks

Self-Service Credentials

Client Libraries / SDKs

Sandbox Environment

Interface Gateway