Cadasto ITEM TAG API

openapi: 3.2.0
info:
  title: Cadasto ITEM TAG API
  x-refined-note:
  - x-spec differs across the merged source definitions and was not carried
  - x-status differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged ITEM_TAG across 2 of this provider''s published API definitions: cadasto-demographic-api-openapi.json, cadasto-ehr-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{baseUrl}/v1
  description: An example openEHR server URL.
  variables:
    baseUrl:
      default: cataniamc.prod.cadasto.com
      description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
- url: https://{baseUrl}/openehr/v1
  description: An example openEHR server URL.
  variables:
    baseUrl:
      default: cataniamc.prod.cadasto.com
      description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
security: []
tags:
- name: Item Tag
  description: Management of ITEM_TAG resources attached to demographic versioned objects (PERSON, AGENT, GROUP, ORGANISATION, ROLE). See also the ITEM_TAG guide.
paths:
  /demographic/tags:
    get:
      operationId: demographic_tags_get
      summary: Get demographic tags
      description: 'Retrieves the list of ITEM_TAG resources associated with any demographic target

        (PERSON, AGENT, GROUP, ORGANISATION, or ROLE), optionally filtered by `tag_key`,

        `tag_value`, and/or `tag_target_path`. When no filter is provided, all tags in

        the demographic store are returned.


        More than one ITEM_TAG may be associated with a single target — they are uniquely

        identified by `(key, target_path)`.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/tag_key'
      - $ref: '#/components/parameters/tag_value'
      - $ref: '#/components/parameters/tag_target_path'
      responses:
        '200':
          $ref: '#/components/responses/200_DEMOGRAPHIC_tags_list'
        '400':
          $ref: '#/components/responses/400'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/agent/{uid_based_id}/tags:
    get:
      operationId: agent_tags_get
      summary: Get AGENT tags
      description: 'Retrieves the list of ITEM_TAG resources associated with the target AGENT

        identified by `uid_based_id`. Returns an empty list when the target has no tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      responses:
        '200':
          $ref: '#/components/responses/200_AGENT_tags_list'
        '404':
          $ref: '#/components/responses/404'
    put:
      operationId: agent_tags_update
      summary: Update AGENT tags
      description: 'Replaces the full ITEM_TAG list for the target AGENT identified by `uid_based_id`

        with the supplied list. Send an empty list to clear all tags. Tags are uniquely

        identified by `(key, target_path)`; duplicates within the request are silently

        deduplicated and the first occurrence wins.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        description: The full new ITEM_TAG list for the target.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
      responses:
        '200':
          $ref: '#/components/responses/200_AGENT_tags_list'
        '204':
          $ref: '#/components/responses/204_tags_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/agent/{uid_based_id}/tags/{key}:
    delete:
      operationId: agent_tags_delete
      summary: Delete AGENT tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target

        AGENT identified by `uid_based_id`. Removes every ITEM_TAG with this key regardless

        of `target_path`.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_tag_deleted'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/group/{uid_based_id}/tags:
    get:
      operationId: group_tags_get
      summary: Get GROUP tags
      description: 'Retrieves the list of ITEM_TAG resources associated with the target GROUP

        identified by `uid_based_id`. Returns an empty list when the target has no tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      responses:
        '200':
          $ref: '#/components/responses/200_GROUP_tags_list'
        '404':
          $ref: '#/components/responses/404'
    put:
      operationId: group_tags_update
      summary: Update GROUP tags
      description: 'Replaces the full ITEM_TAG list for the target GROUP identified by `uid_based_id`

        with the supplied list. Send an empty list to clear all tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        description: The full new ITEM_TAG list for the target.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
      responses:
        '200':
          $ref: '#/components/responses/200_GROUP_tags_list'
        '204':
          $ref: '#/components/responses/204_tags_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/group/{uid_based_id}/tags/{key}:
    delete:
      operationId: group_tags_delete
      summary: Delete GROUP tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target

        GROUP identified by `uid_based_id`.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_tag_deleted'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/organisation/{uid_based_id}/tags:
    get:
      operationId: organisation_tags_get
      summary: Get ORGANISATION tags
      description: 'Retrieves the list of ITEM_TAG resources associated with the target ORGANISATION

        identified by `uid_based_id`. Returns an empty list when the target has no tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      responses:
        '200':
          $ref: '#/components/responses/200_ORGANISATION_tags_list'
        '404':
          $ref: '#/components/responses/404'
    put:
      operationId: organisation_tags_update
      summary: Update ORGANISATION tags
      description: 'Replaces the full ITEM_TAG list for the target ORGANISATION identified by

        `uid_based_id` with the supplied list. Send an empty list to clear all tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        description: The full new ITEM_TAG list for the target.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
      responses:
        '200':
          $ref: '#/components/responses/200_ORGANISATION_tags_list'
        '204':
          $ref: '#/components/responses/204_tags_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/organisation/{uid_based_id}/tags/{key}:
    delete:
      operationId: organisation_tags_delete
      summary: Delete ORGANISATION tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target

        ORGANISATION identified by `uid_based_id`.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_tag_deleted'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/person/{uid_based_id}/tags:
    get:
      operationId: person_tags_get
      summary: Get PERSON tags
      description: 'Retrieves the list of ITEM_TAG resources associated with the target PERSON

        identified by `uid_based_id`. Returns an empty list when the target has no tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      responses:
        '200':
          $ref: '#/components/responses/200_PERSON_tags_list'
        '404':
          $ref: '#/components/responses/404'
    put:
      operationId: person_tags_update
      summary: Update PERSON tags
      description: 'Replaces the full ITEM_TAG list for the target PERSON identified by `uid_based_id`

        with the supplied list. Send an empty list to clear all tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        description: The full new ITEM_TAG list for the target.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
      responses:
        '200':
          $ref: '#/components/responses/200_PERSON_tags_list'
        '204':
          $ref: '#/components/responses/204_tags_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/person/{uid_based_id}/tags/{key}:
    delete:
      operationId: person_tags_delete
      summary: Delete PERSON tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target

        PERSON identified by `uid_based_id`.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_tag_deleted'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/role/{uid_based_id}/tags:
    get:
      operationId: role_tags_get
      summary: Get ROLE tags
      description: 'Retrieves the list of ITEM_TAG resources associated with the target ROLE

        identified by `uid_based_id`. Returns an empty list when the target has no tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      responses:
        '200':
          $ref: '#/components/responses/200_ROLE_tags_list'
        '404':
          $ref: '#/components/responses/404'
    put:
      operationId: role_tags_update
      summary: Update ROLE tags
      description: 'Replaces the full ITEM_TAG list for the target ROLE identified by `uid_based_id`

        with the supplied list. Send an empty list to clear all tags.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/Prefer'
      requestBody:
        description: The full new ITEM_TAG list for the target.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag'
      responses:
        '200':
          $ref: '#/components/responses/200_ROLE_tags_list'
        '204':
          $ref: '#/components/responses/204_tags_updated'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /demographic/role/{uid_based_id}/tags/{key}:
    delete:
      operationId: role_tags_delete
      summary: Delete ROLE tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target

        ROLE identified by `uid_based_id`.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/uid_based_id_for_tags'
      - $ref: '#/components/parameters/key'
      responses:
        '204':
          $ref: '#/components/responses/204_tag_deleted'
        '404':
          $ref: '#/components/responses/404'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /ehr/{ehr_id}/tags:
    get:
      operationId: ehr_tags_get
      summary: Get EHR tags
      description: 'Retrieves the list of ITEM_TAG resources associated with any target VERSIONED_OBJECT

        within the EHR identified by `ehr_id`.


        The list can be filtered by `tag_key`, `tag_value`, or `tag_target_path` query parameters.

        When no filter is provided, all ITEM_TAG resources for the EHR are returned.


        Returns an empty list when the EHR has no tags matching the filter.


        More than one ITEM_TAG may be associated with a single target — they are uniquely identified

        by their `(key, target_path)` pair.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/tag_key_2'
      - $ref: '#/components/parameters/tag_value_2'
      - $ref: '#/components/parameters/tag_target_path_2'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_ItemTagList_retrieved'
        '400':
          $ref: '#/components/responses/400_2'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id'
    servers:
    - url: https://{baseUrl}/openehr/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /ehr/{ehr_id}/composition/{uid_based_id}/tags:
    get:
      operationId: composition_tags_get
      summary: Get COMPOSITION tags
      description: 'Retrieves the list of all ITEM_TAG resources associated with the target COMPOSITION

        identified by `uid_based_id` and owned by the EHR identified by `ehr_id`.


        > **Cadasto exception:** the `uid_based_id` must be a `versioned_object_uid` (HIER_OBJECT_ID).

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported.


        Returns an empty list when the target has no tags. More than one ITEM_TAG may be

        associated with a single target — they are uniquely identified by their `(key, target_path)` pair.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/uid_based_id_for_tags_2'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_ItemTagList_retrieved'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
    put:
      operationId: composition_tags_update
      summary: Update COMPOSITION tags
      description: 'Replaces the full ITEM_TAG list for the target COMPOSITION identified by `uid_based_id`

        and owned by the EHR identified by `ehr_id`.


        Replace semantics: the supplied list becomes the complete tag set. Tags that were present

        but are not in the new list are removed. Sending an empty list clears all tags.


        > **Cadasto exception:** the `uid_based_id` must be a `versioned_object_uid` (HIER_OBJECT_ID).

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported.


        More than one ITEM_TAG may be associated with a single target — they are uniquely identified

        by their `(key, target_path)` pair.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/uid_based_id_for_tags_2'
      - $ref: '#/components/parameters/Prefer_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag_2'
      responses:
        '200':
          $ref: '#/components/responses/200_COMPOSITION_ItemTagList_updated'
        '204':
          $ref: '#/components/responses/204_ItemTag_updated'
        '400':
          $ref: '#/components/responses/400_2'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
    servers:
    - url: https://{baseUrl}/openehr/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /ehr/{ehr_id}/composition/{uid_based_id}/tags/{key}:
    delete:
      operationId: composition_tags_delete
      summary: Delete COMPOSITION tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target COMPOSITION

        identified by `uid_based_id` and owned by the EHR identified by `ehr_id`.


        > **Cadasto exception:** the `uid_based_id` must be a `versioned_object_uid` (HIER_OBJECT_ID).

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/uid_based_id_for_tags_2'
      - $ref: '#/components/parameters/key_2'
      responses:
        '204':
          $ref: '#/components/responses/204_ItemTag_updated'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id_or_key'
    servers:
    - url: https://{baseUrl}/openehr/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags:
    get:
      operationId: ehr_status_tags_get
      summary: Get EHR_STATUS tags
      description: 'Retrieves the list of all ITEM_TAG resources associated with the target EHR_STATUS

        identified by `uid_based_id` and owned by the EHR identified by `ehr_id`.


        > **Cadasto exception:** the `uid_based_id` must be a `versioned_object_uid` (HIER_OBJECT_ID).

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported.


        Returns an empty list when the target has no tags. More than one ITEM_TAG may be

        associated with a single target — they are uniquely identified by their `(key, target_path)` pair.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/uid_based_id_for_tags_2'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_ItemTagList_retrieved'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
    put:
      operationId: ehr_status_tags_update
      summary: Update EHR_STATUS tags
      description: 'Replaces the full ITEM_TAG list for the target EHR_STATUS identified by `uid_based_id`

        and owned by the EHR identified by `ehr_id`.


        Replace semantics: the supplied list becomes the complete tag set. Tags that were present

        but are not in the new list are removed. Sending an empty list clears all tags.


        > **Cadasto exception:** the `uid_based_id` must be a `versioned_object_uid` (HIER_OBJECT_ID).

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported.


        More than one ITEM_TAG may be associated with a single target — they are uniquely identified

        by their `(key, target_path)` pair.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/uid_based_id_for_tags_2'
      - $ref: '#/components/parameters/Prefer_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/UpdateItemTag_2'
      responses:
        '200':
          $ref: '#/components/responses/200_EHR_STATUS_ItemTagList_updated'
        '204':
          $ref: '#/components/responses/204_ItemTag_updated'
        '400':
          $ref: '#/components/responses/400_2'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id'
    servers:
    - url: https://{baseUrl}/openehr/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /ehr/{ehr_id}/ehr_status/{uid_based_id}/tags/{key}:
    delete:
      operationId: ehr_status_tags_delete
      summary: Delete EHR_STATUS tag by key
      description: 'Deletes the ITEM_TAG resource(s) identified by `key`, associated with the target EHR_STATUS

        identified by `uid_based_id` and owned by the EHR identified by `ehr_id`.


        > **Cadasto exception:** the `uid_based_id` must be a `versioned_object_uid` (HIER_OBJECT_ID).

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported.'
      tags:
      - Item Tag
      parameters:
      - $ref: '#/components/parameters/ehr_id'
      - $ref: '#/components/parameters/uid_based_id_for_tags_2'
      - $ref: '#/components/parameters/key_2'
      responses:
        '204':
          $ref: '#/components/responses/204_ItemTag_updated'
        '404':
          $ref: '#/components/responses/404_unknown_ehr_id_or_uid_based_id_or_key'
    servers:
    - url: https://{baseUrl}/openehr/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
components:
  parameters:
    Prefer:
      name: Prefer
      in: header
      description: 'RFC 7240 preference header. Multiple tokens may be sent in a single header as a

        comma-separated list (e.g. `Prefer: return=representation, include_item_tags`)

        or as repeated headers. Cadasto recognises the following tokens:


        | Token | Where it applies | Effect |

        |-------|------------------|--------|

        | `return=representation` | write endpoints | Return the full updated resource in the response body. |

        | `return=identifier` | write endpoints | Return only the resource identifier (e.g. the `uid`). |

        | `return=minimal` (default on writes) | write endpoints | Empty response body. |

        | `include_item_tags` *(Cadasto extension)* | read endpoints, and write endpoints when the request does not already carry an `openehr-item-tag` header | Emit the `openehr-item-tag` response header with the current tags. On writes that ship `openehr-item-tag` in the request, the token is implied — the response always echoes the tags. Omitted by default on reads. See the [ITEM_TAG guide](/docs/guides/item-tag) for details. |


        The `Preference-Applied` response header echoes the tokens the server actually honoured (`return=`, plus `include_item_tags` / `resolve_refs` when applied).

        '
      required: false
      style: simple
      schema:
        type: string
    uid_based_id_for_tags:
      name: uid_based_id
      in: path
      description: 'An identifier in the form of a HIER_OBJECT_ID identifier taken from

        VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`).


        > **Cadasto exception:** unlike the upstream openEHR ITS-REST specification,

        > Cadasto only accepts the `versioned_object_uid` form on `/tags` endpoints.

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported —

        > tags are scoped to the versioned object as a whole.

        '
      required: true
      style: simple
      schema:
        type: string
        format: uuid
    tag_value:
      name: tag_value
      in: query
      description: Filter by ITEM_TAG `value`.
      required: false
      style: form
      explode: true
      schema:
        type: string
    tag_key:
      name: tag_key
      in: query
      description: Filter by ITEM_TAG `key` (exact, case-insensitive match).
      required: false
      style: form
      explode: true
      schema:
        type: string
    key:
      name: key
      in: path
      description: The ITEM_TAG key.
      required: true
      style: simple
      schema:
        type: string
    tag_target_path:
      name: tag_target_path
      in: query
      description: Filter by ITEM_TAG `target_path`.
      required: false
      style: form
      explode: true
      schema:
        type: string
    Prefer_2:
      name: Prefer
      in: header
      description: 'RFC 7240 preference header. Multiple tokens may be sent in a single header as a

        comma-separated list (e.g. `Prefer: return=representation, include_item_tags`)

        or as repeated headers. Cadasto recognises the following tokens:


        | Token | Where it applies | Effect |

        |-------|------------------|--------|

        | `return=representation` | write endpoints | Return the full updated resource in the response body. |

        | `return=minimal` (default on writes) | write endpoints | Empty response body. |

        | `include_item_tags` *(Cadasto extension)* | read endpoints, and write endpoints when the request does not already carry an `openehr-item-tag` header | Emit the `openehr-item-tag` response header with the current tags. On writes that ship `openehr-item-tag` in the request, the token is implied — the response always echoes the tags. Omitted by default on reads. See the [ITEM_TAG guide](/docs/guides/item-tag) for details. |


        The `Preference-Applied` response header echoes the tokens the server actually honoured (`return=`, plus `include_item_tags` / `resolve_refs` when applied).

        '
      required: false
      style: simple
      schema:
        type: string
        examples:
        - return=representation, include_item_tags
    uid_based_id_for_tags_2:
      name: uid_based_id
      in: path
      description: 'An identifier in the form of a HIER_OBJECT_ID identifier taken from

        VERSIONED_OBJECT.uid.value (i.e. a `versioned_object_uid`).


        > **Cadasto exception:** unlike the upstream openEHR ITS-REST specification,

        > Cadasto only accepts the `versioned_object_uid` form on `/tags` endpoints.

        > Targeting a specific version with an OBJECT_VERSION_ID is **not** supported —

        > tags are scoped to the versioned object as a whole.

        '
      required: true
      style: simple
      schema:
        type: string
        format: uuid
        examples:
        - 8849182c-82ad-4088-a07f-48ead4180515
    ehr_id:
      name: ehr_id
      in: path
      description: 'EHR identifier taken from EHR.ehr_id.value.

        '
      required: true
      style: simple
      schema:
        type: string
        examples:
        - 7d44b88c-4199-4bad-97dc-d78268e01398
    tag_value_2:
      name: tag_value
      in: query
      description: Filter by ITEM_TAG `value`.
      required: false
      style: form
      explode: true
      schema:
        type: string
        examples:
        - follow-up
    tag_key_2:
      name: tag_key
      in: query
      description: Filter by ITEM_TAG `key` (exact, case-insensitive match).
      required: false
      style: form
      explode: true
      schema:
        type: string
        examples:
        - flag
    key_2:
      name: key
      in: path
      description: The ITEM_TAG key.
      required: true
      style: simple
      schema:
        type: string
        examples:
        - flag
    tag_target_path_2:
      name: tag_target_path
      in: query
      description: Filter by ITEM_TAG `target_path`.
      required: false
      style: form
      explode: true
      schema:
        type: string
        examples:
        - /composition/start_time/value
  responses:
    200_PERSON_tags_

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cadasto/refs/heads/main/openapi/cadasto-item-tag-api-openapi.yml