API Access

Every Medipal instance exposes a REST API. The web application and the mobile app use it, and third-party systems can use the same API to read and write questionnaires, enrollments, submissions, patients and configuration.

Authentication

Integrations authenticate with an API key created by an administrator in the web application. See API Keys for how keys are created and revoked.

Send the key on every request in one of two ways:

Header	Example
Authorization: Bearer <key>	Authorization: Bearer mp_key_…
X-API-KEY: <key>	X-API-KEY: mp_key_…

Keys always start with mp_key_. The full key is shown once, at creation; store it in your own secret store.

A key acts on behalf of the administrator who created it and carries the subset of permissions chosen at creation. If that administrator's permissions are later reduced, the key's effective permissions shrink with them. Keys have an expiry date chosen at creation and can be revoked at any time.

Permissions

Every endpoint requires one or more scopes of the form resource:action, where the action is one of read, write, delete, manage or execute. Resources include questionnaires, folders, enrollments, patients, submissions, users, permissions, devices, webhooks, event subscriptions, workflows, plugins, vault entries, clinical sources, consent documents, analytics and configuration.

The integration role is intended for API keys: it holds every scope except administration of authentication itself. Choose the narrowest set of scopes an integration needs when creating its key. A request without a required scope is refused with a 403 response.

Discovering the API

Each instance serves its own OpenAPI document at /openapi.json, reflecting exactly the version that instance runs. Use it to browse endpoints, request and response schemas, and required scopes, or to generate a client in your language of choice.

Partners can also obtain a typed TypeScript client and a matching request validation package from the private registry. The client exposes one method per endpoint with typed inputs and outputs; the validation package checks payloads against the same schemas before a request leaves your system.

Collection endpoints

Endpoints that return lists share one set of query conventions.

Feature	Parameters	Notes
Pagination	limit, offset	The response includes total, has_next and has_previous.
Sorting	sort_by, sort_dir (asc or desc)	Without sort_by the order is stable, newest first.
Equality	<field>=<value>	Several filters are combined with AND.
Operators	<field>__<op>=<value>	ne, lt, lte, gt, gte, in, not_in (comma-separated), ilike (with %).
Soft delete	include_deleted, only_deleted	Deleted records are hidden by default and can be restored.

Sortable and filterable fields differ per endpoint. When an unsupported field or operator is used, the error response lists the valid ones for that endpoint.

Errors

Errors are returned as JSON with a single error object containing a machine-readable code, a human-readable message and optional details. Treat the code as the stable contract.

HTTP status	Meaning
400	The request is malformed or a query parameter is invalid.
401	The key is missing, expired or revoked.
403	The key lacks a required scope, or the resource is forbidden.
404	The resource does not exist or is not visible to the caller.
409	The request conflicts with current state (for example a slot that already has a submission).
422	The body fails schema validation; details lists the fields.
5xx	A temporary server-side problem; retry with backoff.

Retries and idempotency

• Reads are safe to retry.
• Creating a submission for a schedule slot is idempotent by design: a slot accepts one submission, and a repeat returns a conflict rather than a duplicate.
• For other writes, check for the resource before re-sending after a timeout.
• Back off exponentially on 5xx responses and on connection errors.

Public endpoints

Two endpoints are reachable with an API key alone and are used by patient-facing channels:

• Public consent documents — returns the consent documents an organisation has published for pairing and enrollment.
• Anonymous questionnaire submission — accepts answers for questionnaires shared through an anonymous link. See Anonymous Questionnaires.

Good practices

• One key per integration, named after the system that uses it, with the minimum scopes.
• Rotate keys on a schedule and revoke immediately when a system is decommissioned.
• Use webhooks for change notification instead of polling collections. See Events & Webhooks.
• Read the instance's /openapi.json after each upgrade to pick up new fields.