# Clinia Platform Documentation

> Documentation for the Clinia health data platform: the Data Fabric and the REST API reference.

- Documentation

  - **About Clinia**
  - [Clinia Platform](/): A composable health data platform for ingesting, governing and searching clinical data.

  - **Core Concepts**
  - [Authentication](/explanation/authentication): Learn how to authenticate with Clinia's API using API keys.
  - Data Model
    - [Data Sources](/explanation/data-model/data-sources): Understand how sources organize resources and relationships before they enter the registry
    - [Profiles & Relationships](/explanation/data-model/profiles-relationships): Understand how to define schemas and validation rules in each source
    - [Partitions](/explanation/data-model/partitions): Understand how partitions expose unified data for search and downstream consumption
    - [Traversed Properties](/explanation/data-model/traversed-property): Learn how to configure traversal rules for your MDM partitions without denormalizing data.
  - Data Types
    - [Base Data Types](/explanation/data-types/base-types): Explore the primitive and composite types that power Clinia schemas
    - [Clinia Complex Types](/explanation/data-types/clinia-types): Discover the opinionated data structures Clinia provides for healthcare interoperability
  - Field Validation
    - [Basics](/explanation/field-validation/basic): Understand the core validation rules available on Clinia profiles and relationship definitions
    - [Conditional Validation](/explanation/field-validation/advanced): Apply conditional logic, nested constraints, and cardinality to Clinia schemas
    - [Vocabulary Validation](/explanation/field-validation/vocabulary): Bind fields to vocabularies to enforce controlled terminology
  - Ingestion Pipeline
    - [Basics](/explanation/ingestion-pipeline/basics): Understand how Clinia pipelines process data between ingestion and persistence
    - [Built-in Processors](/explanation/ingestion-pipeline/built-in-processors): Catalog of processors available out of the box in Clinia ingestion pipelines
    - [Custom Processors](/explanation/ingestion-pipeline/custom-processor): Extend ingestion pipelines with bespoke logic when built-in processors are not enough
  - [Operators](/explanation/operator): Understand how Clinia's operators enable precise search and filtering across the platform
  - [Error Codes and Types](/explanation/errors): Common error codes and types returned by Clinia's API.

  - **Search**
  - [Search Parameters](/explanation/search): Understand how to structure and use search parameters for comprehensive querying in Clinia's Data Partition API
  - [Highlighting](/guides/search/search-highlights): How to highlight search results
  - [Transactional Search](/guides/search/traversed-property): Use traversed properties in the Search API to answer transactional questions in real time.
  - [Hybrid Search](/guides/search/hybrid-search): Combine lexical and semantic retrieval for high recall and precision.

  - **Configuring Data Sources**
  - [Data sources](/explanation/sources/data-source): Define the upstream systems that own records, schemas, and synchronization rules.
  - [Profiles](/explanation/sources/profile): Model resource schemas, validation, and contained components for each data source.
  - [Relationship definitions](/explanation/sources/relationship): Model how profiles connect, including include keys, cardinalities, and relationship properties.

  - **Configuring Partitions**
  - [MDM partitions](/explanation/partitions/mdm-partition): Serve unified records reconciled from multiple sources through the data partition API.

  - **Managing Data**
  - [Tasks](/guides/managing-data/tasks): Process large volumes of registry operations efficiently using the bulk API or ensure atomicity with bundle requests
  - [Browse](/guides/managing-data/browse): Iterate through large datasets in selected partitions using a cursor-based snapshot for consistent bulk extraction with filtering and property selection.
  - [Purge](/guides/managing-data/purge): Bulk delete all resources or relationships of a specific type from a data source using the Purge API endpoint
  - [Historical Import](/guides/managing-data/historical-import): Preserve original timestamps and identifiers when migrating historical data into Clinia.

  - **Master Data Management**
  - [What is Master Data Management?](/explanation/mdm/overview): Overview of Clinia’s MDM module for unified collections, entity resolution and queues
  - Entity Resolution
    - [Overview](/explanation/mdm/entity-resolution/overview): How Clinia identifies and links records across sources to represent a single real‑world entity
    - [Resolution Outcomes](/explanation/mdm/entity-resolution/outcome): Understanding no match, definitive match, and possible match outcomes and queue handling
    - [Resolution Preview](/explanation/mdm/entity-resolution/preview): Preview resolution outcomes before ingestion to validate rules and anticipate matches

  - **Terminology**
  - [Vocabularies](/explanation/vocabularies): Understanding vocabularies as containers for clinical terminology concepts in Clinia
  - [Concepts](/explanation/concepts): Understanding clinical concepts as the fundamental units of terminology in Clinia

  - **Identity and Access Management**
  - [Overview](/iam/iam-overview): Overview of Clinia's Identity and Access Management (IAM) module, including users, service accounts, roles, and permissions.
  - [Users and Service Accounts](/iam/users): Differences between user accounts and service accounts in Clinia IAM and how they authenticate and access the platform.

  - **Role**
  - [Overview](/iam/roles): How roles work in Clinia IAM, including built-in roles and guidance on assigning and managing role-based access.
  - [User-Defined Policies](/iam/user-defined-policies): Fine-grained access controls that constrain system-defined permissions to specific entities like data sources, profiles, or partitions.
  - [System-Defined Permissions](/iam/system-defined-permissions): Predefined permissions that compose roles, with notes on wildcards and when to use user-defined policies for granular access.
- Use Cases

  - **Journeys**
  - [Provider Search](/guides/journeys/provider-search): How-to setup a provider search experience for your patient portal.
- API Reference
  - Registry
    - Browse
      - [Browse accross resource or relationship collections in the registry](/api-reference/registry/browse/browse-accross-resource-or-relationship-collections-in-the-registry): Browse across resource or relationship collections in the registry.
This endpoint only accept federated search paths, which means that when using an operator it expects the collection type and collection key to be specified in the path.
For example, `resources.<collectionKey>.<propertyKey>`.

In order to initiate a browse session, you can specifiy in the body the `v1BrowseParameters` object with the following properties:
- `filter`: A filter to apply to the browse session. Can contain any valid search operators (all except KNN).
- `perPage`: The number of results to return per batch. Defaults to 100.

Once the browse session is initiated, you can use the `cursor` returned in the response to continue browsing through the results.
The `cursor` is a string that keeps track of the current position in the browse session and can be used to fetch the next batch of results.

A browse session lives for 5 minutes, after which it will be automatically closed and a 404 error will be returned if you try to continue browsing.
The session is a rolling session, meanining that each new request will extend the session by 5 minutes from the time of the request.

A browse response contains the following properties:
- `hits`: An array of results that match the browse session.
- `meta`: An object containing metadata about the browse session, including the `cursor` and the total number of results available in the browse session.

You should use the `hits` length to check if there are more results to browse.
If `hits > 0` is true, you can use the `meta.cursor` to fetch the next batch of results.
If `hits > 0` is false, it means that you have reached the end of the browse session and there are no more results to browse.
    - Bulk
      - [Bulk create, upsert, or delete relationships](/api-reference/registry/bulk/bulk-create-upsert-or-delete-relationships): Bulk create, upsert, or delete relationships. The request body should contain a list of operations.
All operations will be processed even if some of them fail.
      - [Bulk create, upsert, or delete resources](/api-reference/registry/bulk/bulk-create-upsert-or-delete-resources): Bulk create, upsert, or delete resources. The request body should contain a list of operations.
All operations will be processed even if some of them fail.
    - Bundle
      - [Bundle resource and relationship operations to be processed](/api-reference/registry/bundle/bundle-resource-and-relationship-operations-to-be-processed): Send a bundle of operations, including resource and relationship operations, to be processed atomically by the system.

Notes:
- Order of Processing: Resource operations are executed first, followed by relationship operations.
- Atomicity: The system processes the entire bundle as a single atomic transaction.
  - If all operations succeed, the changes are committed.
  - If any operation fails, all operations are rolled back, ensuring no partial changes.
    - Collections
      - [Create or update a registry collection](/api-reference/registry/collections/create-or-update-a-registry-collection): Create or update a registry collection.
      - [Get a Collection from the registry](/api-reference/registry/collections/get-a-collection-from-the-registry): Get a Collection from the registry.
      - [List all collections in a source](/api-reference/registry/collections/list-all-collections-in-a-source): List all collections in a registry.
    - Pipeline executions
      - [Get a pipeline execution](/api-reference/registry/pipeline-executions/get-a-pipeline-execution): Get a pipeline execution.
      - [Query pipeline executions](/api-reference/registry/pipeline-executions/query-pipeline-executions): Query the pipeline executions of a source.
The fields that can be used to filter or sort pipeline executions are:
- `id`: The pipeline execution id.
- `pipelineDefinitionId`: The pipeline definition id.
- `createdAt`: The pipeline execution creation timestamp.
- `updatedAt`: The pipeline execution last update timestamp.
- `status`: The pipeline execution status.
- `operation.action`: The action of the operation that triggered the pipeline execution.
- `operation.taskId`: The id of the task that triggered the pipeline execution.
- `operation.target.targetType`: The type of the target that triggered the pipeline execution. It can be 'RESOURCE' or 'RELATIONSHIP'.
- `operation.target.type`: The type of the resource or relationship that triggered the pipeline execution.
- `operation.target.id`: The id of the resource or relationship that triggered the pipeline execution.
- `reviewAssignment.reviewerId`: The id of the reviewer assigned to review the operation that triggered the pipeline execution, if any. Note: this field is only available as a filter, not as a sort field. It also only supports the equality operator.
    - Purge
      - [Get the result of a purge request](/api-reference/registry/purge/get-the-result-of-a-purge-request): Get the result of a purge request.
      - [List purge operations](/api-reference/registry/purge/list-purge-operations): List purge operations.
      - [Purge operation request for resources or relationships](/api-reference/registry/purge/purge-operation-request-for-resources-or-relationships): Purge operation request for resources or relationships.
    - Relationships
      - [Create a relationship between two resources in the registry](/api-reference/registry/relationships/create-a-relationship-between-two-resources-in-the-registry): Create a relationship between two resources in the registry.
      - [Delete a relationship between two resources in the registry](/api-reference/registry/relationships/delete-a-relationship-between-two-resources-in-the-registry): Delete a relationship between two resources in the registry.
      - [Get a relationship from the registry](/api-reference/registry/relationships/get-a-relationship-from-the-registry): Get a relationship from the registry.
      - [Update a relationship between two resources in the registry](/api-reference/registry/relationships/update-a-relationship-between-two-resources-in-the-registry): Update a relationship between two resources in the registry.
The `from` and `to` fields in the body are ignored in favor of respecting the `id` path argument.
    - Resources
      - [Create a contained resource in registry](/api-reference/registry/resources/create-a-contained-resource-in-registry): Create a contained resource in registry.
      - [Create a resource in the registry](/api-reference/registry/resources/create-a-resource-in-the-registry): Create a resource in the registry.
      - [Delete a contained resource in the registry](/api-reference/registry/resources/delete-a-contained-resource-in-the-registry): Delete a contained resource in the registry.
      - [Delete a resource from the registry](/api-reference/registry/resources/delete-a-resource-from-the-registry): Delete a resource from the registry.
      - [Get a contain resource from the registry](/api-reference/registry/resources/get-a-contain-resource-from-the-registry): Get a contain resource from the registry.
      - [Get a resource from the registry](/api-reference/registry/resources/get-a-resource-from-the-registry): Get a resource from the registry.
      - [Upsert a contained resource in the registry](/api-reference/registry/resources/upsert-a-contained-resource-in-the-registry): Upsert a contained resource in the registry.
      - [Upsert a resource in the registry](/api-reference/registry/resources/upsert-a-resource-in-the-registry): Upsert a resource in the registry.
    - Search
      - [Run multiple queries](/api-reference/registry/search/run-multiple-queries): Execute several queries within a single request. It is possible to send multiple query items, where each of the item can be either a regular query or a federated query.
To trigger a federated query, one must specify more then one collection key in the item.
      - [Search accross resource or relationship collections in the registry](/api-reference/registry/search/search-accross-resource-or-relationship-collections-in-the-registry): Search across resource or relationship collections in the registry.
This endpoint suppport both regular and federated search depending on the number of collection keys specified in the path.
If the search is done on one multiple collections are specified, it must use federated search paths. This means that operators expect the collection type and collection key to be specified in the path.
For example, `resources.<collectionKey>.<propertyKey>`.
If the search is done on a single collection, both regular and federated search paths are supported.
    - Task
      - [Get a task from the registry](/api-reference/registry/task/get-a-task-from-the-registry): Get the operation receipts related to a task id.
    - Versionhistory
      - [Get a specific history item](/api-reference/registry/versionhistory/get-a-specific-history-item): Get a single version history entry by its operation ID.
The full data payload of the entity at that point in time can optionally be included.
      - [Get the history for a record or relationship](/api-reference/registry/versionhistory/get-the-history-for-a-record-or-relationship): Retrieves a list of all operations performed on a specific source entity (record or relationship).
Results can be paginated and filtered by a date range.
  - Data Catalog
    - Partitions
      - [Create a data partition](/api-reference/data-catalog/partitions/create-a-data-partition): Create a data partition.
      - [Get a data partition](/api-reference/data-catalog/partitions/get-a-data-partition): Get a data partition.
      - [List the data partitions](/api-reference/data-catalog/partitions/list-the-data-partitions): List the data partitions.
    - Sources
      - [Create a data source](/api-reference/data-catalog/sources/create-a-data-source): Create a data source.
      - [Get a data source](/api-reference/data-catalog/sources/get-a-data-source): Get the data source with the given key.
      - [List the data sources](/api-reference/data-catalog/sources/list-the-data-sources): List the data sources.
  - Data Partition
    - Browse
      - [Browse accross resource or relationship collections in the data partition](/api-reference/data-partition/browse/browse-accross-resource-or-relationship-collections-in-the-data-partition): Browse across resource or relationship collections in the data partition.
This endpoint only accept federated search paths, which means that when using an operator it expects the collection type and collection key to be specified in the path.
For example, `resources.<collectionKey>.<propertyKey>`.

In order to initiate a browse session, you can specifiy in the body the `v1BrowseParameters` object with the following properties:
- `filter`: A filter to apply to the browse session. Can contain any valid search operators (all except KNN).
- `perPage`: The number of results to return per batch. Defaults to 100.

Once the browse session is initiated, you can use the `cursor` returned in the response to continue browsing through the results.
The `cursor` is a string that keeps track of the current position in the browse session and can be used to fetch the next batch of results.

A browse session lives for 5 minutes, after which it will be automatically closed and a 404 error will be returned if you try to continue browsing.
The session is a rolling session, meanining that each new request will extend the session by 5 minutes from the time of the request.

A browse response contains the following properties:
- `hits`: An array of results that match the browse session.
- `meta`: An object containing metadata about the browse session, including the `cursor` and the total number of results available in the browse session.

You should use the `hits` length to check if there are more results to browse.
If `hits > 0` is true, you can use the `meta.cursor` to fetch the next batch of results.
If `hits > 0` is false, it means that you have reached the end of the browse session and there are no more results to browse.
    - Relationships
      - [Retrieve a relationship from a data partition](/api-reference/data-partition/relationships/retrieve-a-relationship-from-a-data-partition): Retrieve a relationship from a data partition.
    - Resources
      - [Browse across a resource includes](/api-reference/data-partition/resources/browse-across-a-resource-includes): Browse across a given resource's includes in the data partition.

In order to initiate a browse session, you can specifiy in the body the `v1BrowseIncludesRequest` object with the following properties:
- `includes`: The list of includes to browse. It can be used to include only a relationship (e.g. `worksAt`) or a relationship and the targeted resource (e.g. `worksAt.clinic`).
- `perPage`: The number of results to return per batch. Defaults to 100.

A browse session lives for 5 minutes, after which it will be automatically closed and a 404 error will be returned if you try to continue browsing.
The session is a rolling session, meaning that each new request will extend the session by 5 minutes from the time of the request.

A browse response contains the following properties:
- `hits`: An array of results that match the browse session.
- `meta`: An object containing metadata about the browse session, including the `cursor` and the total number of results available in the browse session.

You should use the `hits` length to check if there are more results to browse.
If `hits > 0` is true, you can use the `meta.cursor` to fetch the next batch of results.
If `hits > 0` is false, it means that you have reached the end of the browse session and there are no more results to browse.
      - [Retrieve a resource from a data partition](/api-reference/data-partition/resources/retrieve-a-resource-from-a-data-partition): Retrieve a resource from a data partition.
    - Search
      - [Run multiple queries](/api-reference/data-partition/search/run-multiple-queries): Execute several queries within a single request. It is possible to send multiple query items, where each of the item can be either a regular query or a federated query.
To trigger a federated query, one must specify more then one collection key in the item.
      - [Search accross resource or relationship collections in the data partition](/api-reference/data-partition/search/search-accross-resource-or-relationship-collections-in-the-data-partition): Search across resource or relationship collections in the data partition.
This endpoint only accepts federated search paths, which means that one using an operator it expects the collection type and collection key to be specified in the path.
For example, `resources.<collectionKey>.<propertyKey>`. Filters, sorting, aggregations and highlighting use the same federated path syntax.
      - [Search relationships of a specific type in the data partition](/api-reference/data-partition/search/search-relationships-of-a-specific-type-in-the-data-partition): Search relationships of a specific type in the data partition.
      - [Search resources of a specific collection in the data partition](/api-reference/data-partition/search/search-resources-of-a-specific-collection-in-the-data-partition): Search resources of a specific collection in the data partition.
  - MDM
    - Collections
      - [Create a collection in the MDM](/api-reference/mdm/collections/create-a-collection-in-the-mdm): Create a collection in the MDM.
      - [Execute a entity resolution preview for a given set of data (resolution properties) and identifiers](/api-reference/mdm/collections/execute-a-entity-resolution-preview-for-a-given-set-of-data-resolution-properties-and-identifiers): This endpoint allows you to preview/simulate the outcome of the entity resolution process for the given collection.
It returns a list of hits/matches to unified records in the system based the resolution rule of the collection, using the provided data and identifiers.
Use this endpoint to understand how the entity resolution process would behave when injecting a record into the collection, helping you to understand the result on the system.

Note: Entity resolution first checks for duplicate identifiers already present in the system (unified records) and then applies the resolution rule to find matches.
Therefore if matches are found based on identifiers, the resolution properties are ignored.
      - [Get a collection in the MDM](/api-reference/mdm/collections/get-a-collection-in-the-mdm): Get the collection with given key in the MDM.
      - [Get the collection profile](/api-reference/mdm/collections/get-the-collection-profile): Get the profile for the given collection key.
      - [List collections in the MDM](/api-reference/mdm/collections/list-collections-in-the-mdm): List collections in the MDM.
      - [Retrieve a unified resource from mdm collection using its id](/api-reference/mdm/collections/retrieve-a-unified-resource-from-mdm-collection-using-its-id): Retrieve a unified resource from mdm collection using its id.
    - Relationship definitions
      - [Get a relationship definition from the mdm](/api-reference/mdm/relationship-definitions/get-a-relationship-definition-from-the-mdm): Get a relationship definition from the mdm.
      - [List relationship definitions in the mdm](/api-reference/mdm/relationship-definitions/list-relationship-definitions-in-the-mdm): List relationship definitions in the mdm.
  - Terminology
    - Vocabularies
      - [Bulk upsert or delete vocabularies](/api-reference/terminology/vocabularies/bulk-upsert-or-delete-vocabularies): Bulk upsert or delete vocabularies.
Bulk operations are processed synchronously.
      - [Bulk upsert, update or delete concepts](/api-reference/terminology/vocabularies/bulk-upsert-update-or-delete-concepts): Bulk upsert, update or delete concepts.
Bulk operations are processed synchronously.
      - [Delete a concept from a vocabulary](/api-reference/terminology/vocabularies/delete-a-concept-from-a-vocabulary): Delete a concept from a vocabulary.
      - [Delete a vocabulary from the terminology](/api-reference/terminology/vocabularies/delete-a-vocabulary-from-the-terminology): Delete a vocabulary from the terminology.
      - [Get a concept from a vocabulary](/api-reference/terminology/vocabularies/get-a-concept-from-a-vocabulary): Get a concept from a vocabulary.
      - [Get a vocabulary from the terminology](/api-reference/terminology/vocabularies/get-a-vocabulary-from-the-terminology): Get a vocabulary from the terminology.
      - [List all the vocabularies in the terminology](/api-reference/terminology/vocabularies/list-all-the-vocabularies-in-the-terminology): List all the vocabularies in the terminology.
      - [Search for concepts in the terminology](/api-reference/terminology/vocabularies/search-for-concepts-in-the-terminology): Search for concepts in the terminology.
      - [Upsert a concept in a vocabulary](/api-reference/terminology/vocabularies/upsert-a-concept-in-a-vocabulary): Upsert a concept in a vocabulary.
      - [Upsert a vocabulary in the terminology](/api-reference/terminology/vocabularies/upsert-a-vocabulary-in-the-terminology): Upsert a vocabulary in the terminology.
  - Operations
    - Reviewassignments
      - [Bulk assign reviews](/api-reference/operations/reviewassignments/bulk-assign-reviews): Assign one or more reviews to a user.
Existing assignments are overwritten.
      - [Bulk unassign reviews](/api-reference/operations/reviewassignments/bulk-unassign-reviews): Remove the assignee from one or more reviews.
      - [Get a review assignment](/api-reference/operations/reviewassignments/get-a-review-assignment): Get the review assignment for a specific operation.