Building care plans
How a practice creates, checks and releases its care plans through the API or an AI agent, and then accompanies clients along them, worked through with the example "Black Swan® Metabolic Balance Protokoll - 3 Monate".
What a care plan is
A template of the practice made of phases and sessions. Each session has an appointment type, a duration, optionally a call guide, and a time window after the previous session (minDays to maxDays). Templates have versions: a draft can be changed, a released version is fixed and startable, changes create a new version. A care enrollment accompanies a client along one version and carries its copy. Rights: careplans:read/careplans:write and the practice licence right. Care enrollments are client data and also need clients:read/clients:write and client-data enablement of the organization.
1. Fetch the choices
GET /care-plans/options lists the appointment types that can carry a session (bookable for one client, with their durations) and the call guides. If a suitable appointment type is missing, create it with /appointment-types, a guide with /call-guides.
curl https://www.claritos.io/api/v1/care-plans/options -H "Authorization: Bearer capi_…"2. Describe the plan as a whole
Header, phases and sessions go in one call, in the order of the lists. phase points to the position of the phase (from 1). Session 1 has no time window; from session 2 on, minDays and maxDays are required, the distance in calendar days to the start of the previous session. The example is an excerpt from the draft of the Black Swan template. The session "Willkommen" is left out because the distance from it to "Dein Plan" depends on the turnaround of the lab. The practice maintains the version that applies. If the plan starts with an onboarding ("Willkommen" in the Black Swan template), set firstSessionIsOnboarding: true; the app then counts it as session 0.
{
"name": "Black Swan® Metabolic Balance Protokoll - 3 Monate",
"version": "1.0",
"description": "Drei Monate, ein Ziel in den eigenen Worten des Klienten. Rückschläge sind Daten, kein Neustart.",
"phases": [
{ "name": "Vorbereitungsphase", "description": "Zwei Tage." },
{ "name": "Strenge Umstellungsphase", "description": "Mindestens 14 Tage." },
{ "name": "Entspannte Umstellungsphase", "description": "Mehrere Wochen." },
{ "name": "Erhaltungsphase", "description": "Beginnt mit dem Abschluss der Begleitung." }
],
"sessions": [
{ "name": "Dein Plan", "phase": 1, "durationMinutes": 60, "appointmentTypeId": "<id>",
"goal": "Der Klient kann seinen Plan lesen, kennt die acht Regeln und hat ein Startdatum." },
{ "name": "Die erste Woche", "phase": 2, "minDays": 6, "maxDays": 17, "durationMinutes": 45, "appointmentTypeId": "<id>" },
{ "name": "Bilanz der strengen Phase", "phase": 2, "minDays": 8, "maxDays": 19, "durationMinutes": 60, "appointmentTypeId": "<id>" },
{ "name": "Freiheit mit System", "phase": 3, "minDays": 18, "maxDays": 38, "durationMinutes": 45, "appointmentTypeId": "<id>" },
{ "name": "Dein Weg danach", "phase": 3, "minDays": 24, "maxDays": 48, "durationMinutes": 60, "appointmentTypeId": "<id>" }
]
}Modules and variants
Parts of a template that only go into an enrollment when recommended are modules: modules with key and name. A phase belongs to a module through moduleKey, together with its sessions; a session gets its own module only in a phase without one. If phases or sessions in the same call point to a new module, set its key yourself (lowercase letters, digits, hyphens); after that it stays, because rules recommend the module by it. A session can carry one variant per module (variants with moduleKey, callGuideId, durationMinutes): if the module is chosen, the variant's call guide and duration apply. Once a draft has modules or variants, every change must include them; without them the API answers 422 instead of silently removing them. At the start, modules names the chosen keys, without it none; GET /clients/{id}/care-plan-suggestions tells which are recommended.
{
"modules": [{ "key": "schlaf-modul", "name": "Schlaf-Modul" }],
"phases": [
{ "name": "Grundlagen" },
{ "name": "Schlaf", "moduleKey": "schlaf-modul" }
],
"sessions": [
{ "name": "Auftakt", "phase": 1, "durationMinutes": 60, "appointmentTypeId": "<id>" },
{ "name": "Erste Bilanz", "phase": 1, "minDays": 7, "maxDays": 14, "durationMinutes": 45, "appointmentTypeId": "<id>",
"variants": [{ "moduleKey": "schlaf-modul", "durationMinutes": 60 }] },
{ "name": "Schlafprotokoll", "phase": 2, "minDays": 7, "maxDays": 14, "durationMinutes": 45, "appointmentTypeId": "<id>" }
]
}POST /care-enrollments
{ "clientId": "<akte>", "planId": "<fassung>", "coachUserId": "<coach>",
"startDate": "2026-11-02", "modules": ["schlaf-modul"] }3. Dry run
POST /care-plans/validate checks the tree like creating it, without saving. An error comes as 422 with a path (such as body.sessions.2.maxDays). On success you get the gaps to release (gaps), such as a session without appointment type. With ?planId= it checks against an existing draft. Green means: POST /care-plans (new) or PUT /care-plans/{id} (replace a draft) will go through.
curl -X POST https://www.claritos.io/api/v1/care-plans/validate \
-H "Authorization: Bearer capi_…" -H "Content-Type: application/json" \
-d @black-swan.json{ "releasable": true, "gaps": [] }4. Release and new versions
POST /care-plans/{id}/release makes the draft fixed and startable. As in the app, only a person with the approval right or ORG_ADMIN may do this. If the plan still has gaps, the API answers 409 plan-has-gaps with the list. To change it later: POST /care-plans/{id}/versions creates the next version as a draft; running enrollments keep their copy. Retire with …/retire; only what was never used can be deleted.
5. Accompany clients
POST /care-enrollments starts a care enrollment along a released version: client record, coach, start day and the goal in the client's own words. The appointment series is created, nothing is booked yet. Appointments come through a proposal (…/appointment-proposal, scope=next or all) and the booking (…/appointments, all or nothing). GET /care-enrollments/{id} shows the timeline with its light; it turns yellow, never red. A setback is an event (POST …/events, type setback), not a restart. Pause, resume, complete or cancel with …/status; completing and cancelling cancel future appointments.
POST /care-enrollments
{ "clientId": "<akte>", "planId": "<fassung>", "coachUserId": "<coach>",
"startDate": "2026-10-19", "clientGoal": "In den eigenen Worten des Klienten" }
GET /care-enrollments/<id>/appointment-proposal?scope=next
POST /care-enrollments/<id>/appointments
{ "appointments": [{ "position": 2, "startsAt": "2026-10-27T09:00:00Z" }] }6. Running sessions
POST /care-enrollments/{id}/sessions/open opens a session of the plan by its position in the copy; the first call creates it, later calls return the same one. Outside the plan, for example in a crisis, POST /care-enrollments/{id}/sessions creates an ad-hoc session (adHoc, without position) while the enrollment is active or paused. POST /care-sessions/{id}/start starts the session; running is then true for four hours. PATCH /care-sessions/{id} sets the session type (standard, safety, gentle, catch-up, relief) with a short reason. GET /care-enrollments/{id}/sessions lists the opened sessions. The coach works through the call guide in the app; the ID of the run is in guideRunId. Rights as for enrollments.
POST /care-enrollments/<id>/sessions/open
{ "position": 2 }
POST /care-sessions/<sitzung>/start
PATCH /care-sessions/<sitzung>
{ "type": "gentle", "typeReason": "Schlechte Stimmung beim Wiegen" }
POST /care-enrollments/<id>/sessions
{ "name": "Krisengespräch", "type": "relief", "typeReason": "Rückfall nach Urlaub" }With an AI agent
For building a template the compact address /api/mcp/v1/compact (per organization /api/mcp/v1/compact/o/<orgId>) works best: four tools instead of one per endpoint; with full access the normal address has more than 600. The flow for the agent: read this guide (guide with topic care-plans), fetch the choices, check the tree in a dry run until it is green, then create it. The responsible person should release it after reading the plan.
{ "name": "guide", "arguments": { "topic": "care-plans" } }
{ "name": "call_endpoint", "arguments": { "id": "careplans.options" } }
{ "name": "call_endpoint", "arguments": { "id": "careplans.validate", "body": { … } } }
{ "name": "call_endpoint", "arguments": { "id": "careplans.create", "body": { … }, "idempotencyKey": "…" } }