# Get Elements At Revision

## API Name

API Name: Revision – Get Elements at Revision

***

## Overview

This API returns the state of given elements at a specific revision.

It provides a snapshot of elements as they existed at `revisionId`.

MBSE Core uses this API when:

* Field-level diff is not provided by the Revision – Diff API.
* Full element reconstruction is required.
* Snapshot-based synchronization is implemented.

Connector responsibility:

* This API is **not mandatory** if detailed property/tag diff is already provided in the Revision – Diff API.
* If detailed diff is not provided, connector must implement this API.
* Connector must return element state exactly as it existed at the specified revision.

***

### API URI

```bash
GET: /mbse/api/1.0/revisions/{revisionId}/elements
    ?projectId={projectId}
    &elementIds={elementIds}
    &branchId={branchId}
    &expand=PROPERTIES,TAGS,FILES,RELATIONS
    &tags={tags}
    &properties={properties}
```

***

### Path Parameters

| Name       | Mandatory | Type   | Description                                                  |
| ---------- | --------- | ------ | ------------------------------------------------------------ |
| revisionId | True      | String | ID of the revision at which element state must be retrieved. |

***

### URI Parameters

| Name       | Mandatory | Type   | Description                                                                                                                            |
| ---------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| projectId  | True      | String | ID of the project.                                                                                                                     |
| elementIds | True      | List   | List of element IDs whose state is required.                                                                                           |
| branchId   | False     | String | ID of the branch. If omitted, default branch behavior of the end system should apply.                                                  |
| expand     | False     | List   | Controls which additional information should be included in the response. Possible values: `PROPERTIES`, `TAGS`, `FILES`, `RELATIONS`. |
| tags       | False     | List   | List of tag IDs to be included in the response. Applicable only if `TAGS` is included in `expand`.                                     |
| properties | False     | List   | List of property IDs to be included in the response. Applicable only if `PROPERTIES` is included in `expand`.                          |

***

### Expand Parameter Behavior

The `expand` parameter determines which additional fields are included:

* `PROPERTIES`
  * Include element properties.
  * If `properties` parameter is provided, return only those properties.
  * If not provided, return all properties.
* `TAGS`
  * Include tagged values.
  * If `tags` parameter is provided, return only those tags.
  * If not provided, return all tags.
* `FILES`
  * Include files attached to the element.
* `RELATIONS`
  * Include relations of the element.

If `expand` is omitted, only base element metadata must be returned.

***

### Behavior Rules

1. Element state must reflect the exact state at `revisionId`.
2. Only elements specified in `elementIds` must be returned.
3. If an element does not exist at the specified revision, it must not be returned.
4. Filtering by `properties` and `tags` must be respected when provided.
5. If `expand` is not specified, properties, tags, files, and relations must not be returned.
6. Response must not include data beyond what is requested.

***

### Response Payload

The API returns a list of element objects.

#### Sample Response

```json
[
  {
    "elementId": "block_101",
    "name": "System Block",
    "elementTypeId": "Block",
    "qualifiedName": "Model::System::Block",
    "projectId": "123",
    "createdBy": "john.doe",
    "updatedBy": "jane.smith",
    "createdDate": "2026-02-14T08:15:30.000Z",
    "updatedDate": "2026-02-14T10:10:15.000Z",
    "parentElementId": "package_1",
    "properties": {
      "status": "Approved",
      "version": "1.2"
    },
    "tags": {
      "criticality": "High"
    },
    "relations": [
      {
        "relationType": "dependency",
        "targetElementId": "requirement_55",
        "targetElementTypeId": "Requirement",
        "projectId": "123"
      }
    ],
    "files": [
      {
        "fileId": "file_001",
        "fileName": "block-diagram.png",
        "filePath": "/attachments/block-diagram.png",
        "downloadUrl": "https://example.com/download/file_001",
        "label": "Diagram",
        "contentType": "image/png",
        "contentLength": 204800,
        "author": "john.doe",
        "fileType": "IMAGE",
        "lastModifiedDate": "2026-02-14T09:00:00.000Z"
      }
    ]
  }
]
```

***

### Element Object Structure

| Name            | Required | Type                | Description                              |
| --------------- | -------- | ------------------- | ---------------------------------------- |
| elementId       | True     | String              | Unique identifier of the element.        |
| name            | False    | String              | Name of the element.                     |
| elementTypeId   | True     | String              | ID of the element type.                  |
| qualifiedName   | False    | String              | Fully qualified name of the element.     |
| projectId       | True     | String              | Project ID.                              |
| createdBy       | False    | String              | User who created the element.            |
| updatedBy       | False    | String              | User who last updated the element.       |
| createdDate     | False    | String (ISO-8601)   | Creation timestamp.                      |
| updatedDate     | False    | String (ISO-8601)   | Last modification timestamp.             |
| parentElementId | False    | String              | Parent element ID.                       |
| properties      | False    | Map\<String,Object> | Element properties (if expanded).        |
| tags            | False    | Map\<String,Object> | Tagged values (if expanded).             |
| relations       | False    | List                | Element relations (if expanded).         |
| files           | False    | List                | Files attached to element (if expanded). |

***

### Relation Object Structure

| Name                | Required | Type   | Description                                                    |
| ------------------- | -------- | ------ | -------------------------------------------------------------- |
| relationType        | True     | String | Type of relation (association, dependency, realization, etc.). |
| targetElementId     | True     | String | Target element ID.                                             |
| targetElementTypeId | True     | String | Target element type ID.                                        |
| projectId           | True     | String | Project ID.                                                    |
| author              | False    | String | Creator of the relation.                                       |
| createdDate         | False    | String | Relation creation timestamp (ISO-8601).                        |

***

### File Object Structure

| Name             | Required | Type   | Description                             |
| ---------------- | -------- | ------ | --------------------------------------- |
| fileId           | True     | String | Unique file identifier.                 |
| fileName         | True     | String | Name of the file.                       |
| filePath         | False    | String | Path of the file.                       |
| downloadUrl      | False    | String | URL to download the file.               |
| label            | False    | String | File label.                             |
| contentType      | False    | String | MIME type.                              |
| contentLength    | False    | Long   | File size in bytes.                     |
| author           | False    | String | User who uploaded the file.             |
| fileType         | False    | String | Type/category of the file.              |
| lastModifiedDate | False    | String | Last modification timestamp (ISO-8601). |

***

### Example Use Case

#### Get Elements at Specific Revision with Properties and Tags

```bash
GET /mbse/api/1.0/revisions/rev_20260214_002/elements?
projectId=123
&elementIds=block_101,requirement_55
&expand=PROPERTIES,TAGS
```

***

### Implementation Guidelines

1. If detailed property/tag diff is already provided in Revision – Diff API, this API does not need to be implemented.
2. If diff is not provided, connector must:
   * Retrieve full element state at revision.
   * Return only requested elements.
3. Connector must ensure:
   * Revision-consistent state.
   * No mixing of data from other revisions.
   * Accurate filtering of properties and tags.

***

### Design Rationale

This API enables snapshot-based synchronization when:

* Field-level diff is unavailable.
* File-based systems do not support granular diff.
* Full element reconstruction is required.

This keeps the revision layer clean and separates:

* Revision metadata retrieval
* Element-level change detection
* Element snapshot reconstruction


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opstech.gitbook.io/opstech-docs/mbse-connector-sdk-index/mbse-sdk-connector-apis/multi-element-revision-apis/get-elements-at-revision.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.