API Server

The Medipal API server is the single authority in an instance. Every screen in the web app and every questionnaire on a patient's phone is backed by it, and nothing is decided outside it: authentication, permissions, folder configuration, questionnaire revisions, schedules, submissions, secrets, workflows, event delivery, analytics and access to hospital systems all live here.

This section is written for developers and IT teams who evaluate, integrate with or operate the platform. It stays at architecture level; the how-to material for administrators is in the User Guide and the integration recipes are under Integrations.

One instance per organisation

Each organisation runs its own instance: its own API server, database and web app, isolated from every other organisation. There is no shared multi-tenant database. Inside an instance, folders and permissions separate departments, studies and teams; see Folders & Configuration.

Responsibilities

Area	What the server owns	Read more
API	A versioned REST API described by an OpenAPI document generated from the platform schema.	API Design
Authentication	Credentials, multi-factor authentication, Microsoft Entra ID sign-in, device authentication for patients, API keys.	Authentication & Authorization
Authorization	Roles composed of scopes, plus folder and questionnaire permissions.	Authentication & Authorization
Data	The relational model for questionnaires, patients, enrollments, submissions and everything around them.	Data Model
Configuration and vault	Layered configuration validated at startup, encrypted secrets referenced by name, config-as-code reconciliation.	Configuration & Vault
Events	Every domain change becomes an event, stored transactionally and delivered to workflows, subscriptions and webhooks.	Events & Delivery
Workflows	Graph-based automations triggered by events, with conditions, computations, delays, HTTP calls and plugin actions.	Workflow Engine
Plugins	Installable server extensions that expose actions and can read platform data through a scoped host API.	Plugin Runtime
Background jobs	A scheduler with a single active leader running delivery, retry, cleanup, synchronisation and heartbeat jobs.	Background Jobs
Integrations	FHIR and OMOP clinical sources, directory synchronisation with Microsoft Entra ID, outbound webhooks.	EHR Connectors
Analytics	Datasets, charts and dashboards computed from submissions and clinical data.	Analytics
Operations	Database migrations and seeding, a command line interface, structured logs and health endpoints.	Database, CLI, Observability

The API contract

Every instance publishes its own OpenAPI document. It is the same document the typed TypeScript clients of the web and mobile apps are generated from, so what you read there is exactly what the apps use. The interactive documentation is served by the instance itself; ask your administrator for the address of your instance and see API Access for how to authenticate against it.

How the section is organised

1. Architecture & Request Lifecycle: the layers a request passes through and how the schema drives the code.
2. API Design: resource conventions, list endpoints, errors and validation.
3. Authentication & Authorization: who can call what.
4. Data Model: the entities and how they relate.
5. Configuration & Vault: how an instance is configured and how secrets are handled.
6. Runtime: events, the workflow engine, the plugin runtime and background jobs.
7. Operations: database and migrations, the command line interface and observability.