Overview

Services

Getting Started

Before being able to access any of our APIs, the user must be authenticated. Obtain your client credentials (client_id and client_secret) after contacting Cadasto to set up an environment for you.

After you have obtained your client credentials, you can start using the Client Credentials flow. See the authentication guide below.

For a more in depth guide, follow the authentication guide.

Typical Workflow

1. Create an EHR

Auto-generated EHR id:

POST /ehr
Prefer: return=representation
Authorization: Bearer <token>

Get EHR

GET /ehr/{ehr_id}
Accept: application/json
Authorization: Bearer <token>

2. Upload Templates (Definition API)

ADL 1.4 XML:

POST /definition/template/adl1.4
Content-Type: application/xml
Prefer: return=minimal

<template xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.openehrorg/v1">
    <language>
        <terminology_id>
            <value>ISO_639-1</value>
        </terminology_id>
        <code_string>en</code_string>
    </language>
	....
</template>

List templates:

GET /definition/template/adl14

Retrieve template (web template JSON):

GET /definition/template/adl1.4/{template_id}
Accept: application/openehr.wt+json

3. Commit a COMPOSITION

POST /ehr/{ehr_id}/composition
Content-Type: application/json
Prefer: return=representation
Authorization: Bearer <token>

{
	"archetype_node_id": "openEHR-EHR-COMPOSITION.encounter.v1",
	"name": {
		"value": "Vital Signs"
	},
	"uid": {
		"_type": "OBJECT_VERSION_ID",
		"value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::1"
	},
	...
}

Body includes COMPOSITION with language, territory, category, context, composer, content[]. For simplified formats supply openEHR-TEMPLATE_ID if template metadata absent. Response: 201 with Location and possibly full representation.

4. Retrieve or Update a COMPOSITION

Latest version (implicit):

GET /ehr/{ehr_id}/composition/{versioned_object_uid}

Specific version:

GET /ehr/{ehr_id}/composition/{version_uid}

Update (optimistic locking):

PUT /ehr/{ehr_id}/composition/{versioned_object_uid}
If-Match: "<latest_version_uid>"

Delete (logical):

DELETE /ehr/{ehr_id}/composition/{version_uid}

5. Directory (FOLDER)

Create:

POST /ehr/{ehr_id}/directory

Update with concurrency:

PUT /ehr/{ehr_id}/directory
If-Match: "<latest_version_uid>"

Fetch path inside directory at time:

GET /ehr/{ehr_id}/directory?path=episodes/a/b&version_at_time=YYYY-MM-DDThh:mm:ss.sss±hh:mm

6. Contribution (Batch commit)

POST /ehr/{ehr_id}/contribution
Content-Type: application/json

Supply versions array referencing operations and audit metadata.

7. Query Data (AQL)

Ad-hoc POST (recommended for length + params):

POST /query/aql
{
	"q": "SELECT ... WHERE o/data[...] > $temperature",
	"query_parameters": { "temperature": 38.5 }
}

Quick Reference (Cheat Sheet)