# vitagroup AG

> vitagroup AG is a German health-technology company (Mannheim, HRB 727147) that builds the Health Intelligence Platform (HIP), an open, vendor-neutral clinical data platform for hospitals, health regions and research institutions. Its Clinical Data Repository is HIP EHRbase, the commercially supported distribution of EHRbase — the leading open-source openEHR server, which vitagroup operates (ehrbase.org names vitagroup AG as the responsible legal entity). Four OpenAPI documents are published; the primary contract is EHRbase's implementation of the openEHR REST API (ITS-REST).

This file was GENERATED by API Evangelist from vitagroup's published contracts and documentation. vitagroup serves no llms.txt of its own — probed 2026-09-02 at www.vitagroup.ag/llms.txt (404), hip.vitagroup.ag/llms.txt (404) and docs.ehrbase.org/llms.txt (404).

## What this API is

The unit of work is the openEHR record. An EHR is a container for one subject; COMPOSITIONs are the clinical documents committed into it, constrained by an operational template (ADL 1.4 or ADL 2). Everything is append-only and versioned — an update creates a new version, a delete creates a version marked deleted, and any versioned object can be read at an arbitrary past instant. Reading is done with AQL, one query language over the whole record, rather than per-endpoint filters.

The important consequence: the schema is not vitagroup's. It is the openEHR Reference Model. An integrator who already speaks openEHR needs no bespoke connector.

## Deployment

HIP EHRbase is customer-deployed software, not a vendor-hosted multi-tenant API. There is no signup, no API key issuance, no vendor production host and no status page. The only vitagroup-operated instance on the public internet is the sandbox.

- Sandbox (live, unauthenticated, AUTH_TYPE=NONE): https://sandkiste.ehrbase.org/
- Sandbox API base: https://sandkiste.ehrbase.org/ehrbase
- Sandbox Swagger UI: https://sandkiste.ehrbase.org/ehrbase/swagger-ui/index.html
- Live OpenAPI served by that instance: https://sandkiste.ehrbase.org/ehrbase/v3/api-docs
- Container image: https://hub.docker.com/r/ehrbase/ehrbase

## APIs

- [HIP EHRbase openEHR REST API](https://docs.ehrbase.org/api/hip-ehrbase/openehr): 31 paths / 45 operations. EHR, EHR_STATUS, COMPOSITION, DIRECTORY, CONTRIBUTION, versioned objects, ADL 1.4 and ADL 2 templates, AQL execution, server status.
- [HIP EHRbase Admin API](https://docs.ehrbase.org/api/hip-ehrbase/admin): 8 paths / 11 operations. Physical delete and update outside the versioning model, plus Merge EHR. Requires the admin role. Irreversible.
- [HIP EHRbase Item Tag Experimental API](https://docs.ehrbase.org/api/hip-ehrbase/tags): 2 paths / 6 operations. Key/value annotations on EHR_STATUS and COMPOSITION. Explicitly experimental.
- [HIP EHRbase Enterprise API](https://docs.ehrbase.org/api/hip-ehrbase/enterprise): 6 paths / 9 operations. Event Trigger, Multi-tenant provisioning, Transaction Compensation rollback. Closed-source, HIP EHRbase only, bearer JWT required.

## Documentation

- [EHRbase Docs](https://docs.ehrbase.org/): the developer portal.
- [Installation](https://docs.ehrbase.org/docs/EHRbase/Installation): getting started.
- [openEHR Introduction](https://docs.ehrbase.org/docs/EHRbase/openEHR-Introduction/Introduction): data models, templates, creating an EHR, loading data.
- [AQL Introduction](https://docs.ehrbase.org/docs/EHRbase/Explore/AQL/Introduction): SELECT, CONTAINS, WHERE, ORDER BY, configuration.
- [Simplified data template / WebTemplate](https://docs.ehrbase.org/docs/EHRbase/Explore/Simplified-data-template/WebTemplate): the flat and structured JSON formats most application code posts.
- [Security](https://docs.ehrbase.org/docs/EHRbase/Explore/Security): NONE / BASIC / OAUTH modes, role mapping, management endpoint access.
- [Status and metrics](https://docs.ehrbase.org/docs/EHRbase/Explore/Status-And-Metrics): Spring Actuator endpoints, disabled by default.
- [Enterprise Features](https://docs.ehrbase.org/docs/EHRbase/Enterprise-Features/Overview): Yugabyte, ATNA, Event Trigger, Transaction Compensation, Multi-Tenancy, Merge EHR.
- [Breaking changes / UPDATING.md](https://github.com/ehrbase/ehrbase/blob/develop/UPDATING.md): the migration guide. Read this before upgrading; there are no Sunset headers.

## Authentication

Chosen by the OPERATOR at server startup, not fixed by vitagroup. `SECURITY_AUTHTYPE` is one of:

- `NONE` — the default. No credentials. This is what the public sandbox runs.
- `BASIC` — HTTP Basic against a configured user/password and admin user/password.
- `OAUTH` — OAuth 2.0 resource server. Validates a bearer JWT against an operator-configured issuer (Keycloak in HIP) and reads the role from `realm_access.roles` or `scope`. Two levels only: user (default role name `USER`) and admin (default `ADMIN`), both renameable.

The three open-source OpenAPI documents declare NO securitySchemes, so a generated client will not expect an auth failure. Only the enterprise spec declares `bearerAuth`.

## Runtime semantics an agent must know

- **Concurrency**: `If-Match` carrying the `version_uid` is required on `updateComposition`, `updateEhrStatus`, `updateDirectory` and `deleteComposition`. A stale value returns 412 with the current `version_uid` in `ETag`. Re-read and re-apply; never strip the header.
- **Audit**: send `openEHR-AUDIT_DETAILS` on writes. It is persisted with the CONTRIBUTION.
- **Representation**: `Prefer: return=representation` or `return=minimal`.
- **Point in time**: `version_at_time` on versioned reads. A 404 there may mean "nothing at that instant", not "does not exist".
- **Paging**: `offset` and `fetch` on AQL. No cursor, no total count.
- **Idempotency**: NOT supported. No `Idempotency-Key`. `POST .../ehr` and `POST .../composition` are not idempotent. `PUT /rest/openehr/v1/ehr/{ehr_id}` (createEhrWithId) lets you choose the id and is the retry-safe way to create.
- **Errors**: no RFC 9457. Branch on the status code. 400 invalid content, 401 credentials, 403 admin role missing, 404 not found, 409 EHR already exists for that subject, 412 stale If-Match, 422 template still in use, 501 contribution delete withdrawn since 2.0.0.
- **Rate limits**: none published, none observed. No `X-RateLimit-*`, no `Retry-After`, no 429 declared anywhere.
- **Dry run**: not supported.

## Reversibility

- Composition delete is LOGICAL — prior versions stay readable. Recoverable.
- Contribution `rollback` (enterprise only) reverses a whole contribution using the Saga pattern. Documented, but NO time window is stated.
- Every `/rest/admin/**` delete is PHYSICAL and irreversible.
- `mergeEhrs` has no unmerge. vitagroup's own docs: "Even if unmerging data is stored for each merge, the unmerge operation is not possible at the moment."

Do not call an admin delete or a merge without explicit human confirmation.

## Events

HIP EHRbase enterprise ships Event Trigger: an operator registers a rule whose condition is an AQL query and whose action forwards the projection over HTTP, AMQP/RabbitMQ, Kafka or a log sink, firing BEFORE or AFTER a COMPOSITION or EHR_STATUS create/update/delete. There are no vendor-defined event types — the operator defines them. No AsyncAPI document is published, no delivery guarantee is documented, and payloads are not signed.

## SDKs and packages

Java only, from Maven Central, all current as of 2026-08-17/20:

- `org.ehrbase.openehr.sdk:client` 2.35.0 — the REST client SDK
- `org.ehrbase.openehr.sdk:generator-maven-plugin` 2.35.0 — generates typed Java classes from an operational template
- `org.ehrbase.openehr.sdk:aql` 2.35.0, `:web-template` 2.35.0, `:bom` 2.35.0
- `org.ehrbase.openehr:application` / `:server` / `:api` / `:cli` 2.35.1 — the server itself
- Docker: `ehrbase/ehrbase` 2.35.1

There is NO first-party JavaScript, Python, Go, C# or Ruby client. Non-JVM integrators write raw HTTP.

## Standards

openEHR ITS-REST (primary), openEHR Reference Model, AQL, ADL 1.4 / ADL 2, IHE ATNA audit logging (enterprise), OAuth 2.0, HTTP conditional requests (ETag / If-Match). HL7 FHIR and HL7v2 are supported through separate bridge components (FHIR Bridge, openFHIR, FHIRconnect) rather than as a native FHIR server — no FHIR CapabilityStatement is published.

Not implemented: RFC 9457 problem details, RFC 8594 Sunset headers, Idempotency-Key, AsyncAPI, SCIM.

## Source and packages

- [vitagroup GitHub org](https://github.com/vitagroupag)
- [EHRbase server](https://github.com/ehrbase/ehrbase) (Apache-2.0)
- [openEHR SDK](https://github.com/ehrbase/openEHR_SDK)
- [openEHR_models](https://github.com/vitagroupag/openEHR_models) — archetypes and templates for HIP CDR
- [FHIR Bridge](https://github.com/vitagroupag/fhir-bridge), [openFHIR](https://github.com/vitagroupag/openFHIR), [FHIRconnect-spec](https://github.com/vitagroupag/FHIRconnect-spec)
- [Releases / changelog](https://github.com/ehrbase/ehrbase/releases) — semver, Keep a Changelog, current 2.35.1 (2026-08-20)

## Security

- [Responsible disclosure policy](https://github.com/ehrbase/ehrbase/blob/develop/SECURITY.md) — report to ehrbase-security@vitagroup.ag. No bug bounty, no stated SLA, no safe-harbour language.
- No security.txt is served on any vitagroup or ehrbase host.
- No SOC 2, ISO 27001, ISO 13485 or C5 attestation is published, and there is no trust center.

## Company

- [vitagroup AG](https://www.vitagroup.ag/) — Gottlieb-Daimler-Straße 8, 68165 Mannheim, Germany
- [HIP platform](https://hip.vitagroup.ag/en/)
- [HIP Tech Blog](https://hip.vitagroup.ag/en/tech-blog/)
- [Contact](https://hip.vitagroup.ag/en/contact/) — the commercial entry point; there is no self-serve signup and no published pricing
- [Privacy](https://www.vitagroup.ag/en/privacy/) · [Imprint](https://www.vitagroup.ag/en/imprint/)
- [LinkedIn](https://www.linkedin.com/company/vitagroup-ag/)

## Not available

No MCP server. No A2A agent card. No GraphQL. No gRPC or SOAP. No llms.txt. No /.well-known documents of any kind on any host. No status page. No published pricing or plans. No published rate limits. No Postman collection. No public roadmap. No terms of service page.