openapi: 3.2.0
info:
  title: Cadasto Additional Datamap Query API
  version: 1.0.0
  description: 'Additional API on top of the openEHR REST API, specific to Cadasto.

    The endpoints in this specification are Cadasto-specific and are intended

    to make it easier for app builders to interact with openEHR (e.g. datamaps).

    This API only works within Cadasto.'
servers:
- url: https://api.customer.cadasto.io
security:
- bearerAuth: []
tags:
- name: Datamap Query
  description: 'Run datamap queries and manage datamap data.

    Supports ad-hoc XML queries and CRUD via JSON for Cadasto.'
paths:
  /extra/v1/datamap:
    post:
      tags:
      - Datamap Query
      summary: Ad-hoc datamap query (XML body)
      description: Executes an ad-hoc query based on an XML query body.
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/orderBy'
      - $ref: '#/components/parameters/ehrUid'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
      responses:
        '200':
          description: OK
        '400':
          description: Bad request
        '404':
          description: Not found
      operationId: postExtraV1Datamap
      x-operation-id-source: derived
  /extra/v1/datamap/{datamapName}:
    parameters:
    - $ref: '#/components/parameters/datamapName'
    get:
      tags:
      - Datamap Query
      summary: Query datamap data (list)
      description: 'Retrieves a list of data via the datamap.

        Use `ehrUid` as a query parameter to scope results to a specific EHR.


        Example: `/extra/v1/datamap/Rapportage?ehrUid=9f7f3e7a-1111-4b2e-8d7c-222222222222`'
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/orderBy'
      - $ref: '#/components/parameters/ehrUid'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                rapportage_list:
                  summary: Rapportage list (sample)
                  value:
                    data:
                    - vuid: <redacted>
                      episode_uid: <redacted>
                      episode_id: E0100016
                      episode_status: active
                      episode_start: '2025-12-04 15:46:53'
                      episode_end: '9999-12-31 23:59:59'
                      uid: <redacted>
                      version_object_id: 325
                      version_tree_id: 4
                      artefact_id: 240
                      trunk_lifecycle_state: complete
                      Datum en Tijd: '2025-12-10T12:02:00+01:00'
                      Zorgverlener: Code24 Medewerker
                      Zorgverlener_uid: <redacted>
                      Type Contact:
                        code: at0021
                        value: Face to face
                      Rapportage: Example report text...
                    - vuid: <redacted>
                      episode_uid: <redacted>
                      episode_id: E0100016
                      episode_status: active
                      episode_start: '2025-12-04 15:46:53'
                      episode_end: '9999-12-31 23:59:59'
                      uid: <redacted>
                      version_object_id: 326
                      version_tree_id: 2
                      artefact_id: 240
                      trunk_lifecycle_state: complete
                      Datum en Tijd: '2025-12-10T12:02:00+01:00'
                      Zorgverlener: Code24 Medewerker
                      Zorgverlener_uid: <redacted>
                      Type Contact:
                        code: at0022
                        value: Ear to ear
                      Rapportage: Example report text...
                    totalCount: 5
                agent_overview:
                  summary: Agent overview (sample)
                  value:
                    data:
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: HL7
                      version_object_id: 19
                      version_tree_id: 1
                      id: hl7agent
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: FHIR
                      version_object_id: 20
                      version_tree_id: 1
                      id: fhir
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: Systeem
                      version_object_id: 21
                      version_tree_id: 1
                      id: system
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: Client360
                      version_object_id: 22
                      version_tree_id: 1
                      id: client360
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: Automated tester
                      version_object_id: 23
                      version_tree_id: 1
                      id: automated_tester
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: Cadasto client cadasto-fb2eaa45-052f-4292-a501-9f3b6bdf1d89
                      version_object_id: 71
                      version_tree_id: 1
                      id: cadasto-fb2eaa45-052f-4292-a501-9f3b6bdf1d89
                    - uid: <redacted>
                      vuid: <redacted>
                      full_name: Cadasto client cadasto-805bf4cb-2166-4e8a-b31b-cfc5c2c45bdf
                      version_object_id: 72
                      version_tree_id: 1
                      id: cadasto-805bf4cb-2166-4e8a-b31b-cfc5c2c45bdf
                    totalCount: 7
        '400':
          description: Bad request
        '404':
          description: Not found
      operationId: getExtraV1DatamapByDatamapName
      x-operation-id-source: derived
    post:
      tags:
      - Datamap Query
      summary: Create datamap data
      description: Creates new data according to the datamap (JSON body).
      parameters:
      - $ref: '#/components/parameters/ehrUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            examples:
              default:
                value:
                  uid: <redacted>
                  zorgpad_omschrijving: test 2
                  zorgpad_code: test 3
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
              examples:
                default:
                  value:
                    data:
                      vuid: <redacted>
                      uid: <redacted>
                      version_object_id: 329
                      version_tree_id: 2
                      artefact_id: 135
                      trunk_lifecycle_state: complete
                      beslisboom_context: []
                      zorgpad_omschrijving: test 2
                      zorgpad_code: test 3
                      zorgmodules: []
        '400':
          description: Bad request
        '404':
          description: Not found
      operationId: postExtraV1DatamapByDatamapName
      x-operation-id-source: derived
  /extra/v1/datamap/{datamapName}/{uidBasedId}:
    parameters:
    - $ref: '#/components/parameters/datamapName'
    - $ref: '#/components/parameters/uidBasedId'
    get:
      tags:
      - Datamap Query
      summary: Get datamap data (by UID)
      description: Retrieves a single data item by UID.
      parameters:
      - $ref: '#/components/parameters/ehrUid'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              examples:
                default:
                  value:
                    data:
                      vuid: <redacted>
                      uid: <redacted>
                      version_object_id: 329
                      version_tree_id: 2
                      artefact_id: 135
                      trunk_lifecycle_state: complete
                      beslisboom_context: []
                      zorgpad_omschrijving: test 2
                      zorgpad_code: test 3
                      zorgmodules: []
        '400':
          description: Bad request
        '404':
          description: Not found
      operationId: getExtraV1DatamapByDatamapNameByUidBasedId
      x-operation-id-source: derived
    put:
      tags:
      - Datamap Query
      summary: Update datamap data (by UID)
      description: Updates a single data item by UID (JSON body).
      parameters:
      - $ref: '#/components/parameters/ehrUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
        '400':
          description: Bad request
        '404':
          description: Not found
      operationId: putExtraV1DatamapByDatamapNameByUidBasedId
      x-operation-id-source: derived
    delete:
      tags:
      - Datamap Query
      summary: Delete datamap data (by UID)
      description: Deletes a single data item by UID.
      parameters:
      - $ref: '#/components/parameters/ehrUid'
      responses:
        '200':
          description: Deleted
        '400':
          description: Bad request
        '404':
          description: Not found
      operationId: deleteExtraV1DatamapByDatamapNameByUidBasedId
      x-operation-id-source: derived
    head:
      tags:
      - Datamap Query
      summary: Check datamap data exists (by UID)
      description: Checks whether a single data item with the given UID exists.
      parameters:
      - $ref: '#/components/parameters/ehrUid'
      responses:
        '200':
          description: Exists
        '404':
          description: Not found
      operationId: headExtraV1DatamapByDatamapNameByUidBasedId
      x-operation-id-source: derived
components:
  parameters:
    datamapName:
      name: datamapName
      in: path
      required: true
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
    uidBasedId:
      name: uidBasedId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    orderBy:
      name: order_by
      in: query
      required: false
      schema:
        type: string
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
    ehrUid:
      name: ehrUid
      in: query
      required: false
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-ext-urls: {}