# Get Element

## API Name

API Name: Element – Get

***

## Overview

This API retrieves a single element from the end system.

MBSE Core uses this API to:

* Fetch element details
* Perform on-demand synchronization
* Retrieve full element state
* Support relation and file expansion

Connector responsibility:

* Retrieve the element using the end system API with the given `elementId`.
* Respect project and branch scoping.
* Based on `expand` options:
  * Load properties
  * Load tags
  * Load relations
  * Load files
* For tags, connector may need to:
  * Extract tag GUIDs from element metadata
  * Fetch tag details separately
* Fetch relations and files if requested.
* Convert all retrieved data into `MbseElement` format.

***

### API URI

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

***

### Path Parameters

| Name      | Mandatory | Type   | Description                    |
| --------- | --------- | ------ | ------------------------------ |
| elementId | True      | String | ID of the element to retrieve. |

***

### URI Parameters

| Name          | Mandatory | Type   | Description                                                                                                     |
| ------------- | --------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| projectId     | True      | String | ID of the project.                                                                                              |
| elementTypeId | True      | String | ID of the element type.                                                                                         |
| branchId      | False     | String | ID of the branch. If omitted, default branch behavior applies.                                                  |
| expand        | False     | List   | Controls which additional information is included. Possible values: `PROPERTIES`, `TAGS`, `FILES`, `RELATIONS`. |
| properties    | False     | List   | List of property IDs to include. Applicable only if `PROPERTIES` is included in `expand`.                       |
| tags          | False     | List   | List of tag IDs to include. Applicable only if `TAGS` is included in `expand`.                                  |

***

### Expand Parameter Behavior

The `expand` parameter controls what additional data is returned:

#### PROPERTIES

* Include element properties.
* If `properties` is provided, return only those properties.
* If omitted, return all properties.

#### TAGS

* Include tagged values.
* If `tags` is provided, return only those tags.
* If omitted, return all tags.

#### FILES

* Include files attached to the element.

#### RELATIONS

* Include element relations.

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

***

### Behavior Rules

1. The element must be retrieved within the scope of:
   * `projectId`
   * `elementTypeId`
   * Optional `branchId`
2. If element does not exist:
   * Return HTTP `404 Not Found`.
3. If `expand` is not provided:
   * Do not return properties, tags, files, or relations.
4. Respect filtering parameters (`properties`, `tags`).
5. Do not return unrelated data.
6. Response must strictly follow `MbseElement` structure.

***

### Response Payload

#### 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"
    }
  ]
}
```

***

### Response Parameters

#### Element Object

| Name            | Required | Type                | Description                        |
| --------------- | -------- | ------------------- | ---------------------------------- |
| elementId       | True     | String              | Unique element identifier.         |
| name            | False    | String              | Name of the element.               |
| elementTypeId   | True     | String              | ID of the element type.            |
| qualifiedName   | False    | String              | Fully qualified name.              |
| 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 update 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                | Attached files (if expanded).      |

***

### Relation Object

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

***

### File Object

| Name             | Required | Type   | Description                         |
| ---------------- | -------- | ------ | ----------------------------------- |
| fileId           | True     | String | Unique file identifier.             |
| fileName         | True     | String | File name.                          |
| filePath         | False    | String | File path.                          |
| downloadUrl      | False    | String | File download URL.                  |
| label            | False    | String | File label.                         |
| contentType      | False    | String | MIME type.                          |
| contentLength    | False    | Long   | File size in bytes.                 |
| author           | False    | String | File uploader.                      |
| fileType         | False    | String | File category/type.                 |
| lastModifiedDate | False    | String | Last modified timestamp (ISO-8601). |

***

### Example Use Case

#### Get Element with Properties and Tags

```bash
GET /mbse/api/1.0/elements/block_101?
projectId=123
&elementTypeId=Block
&expand=PROPERTIES,TAGS
```

***

### Implementation Guidelines

* Always scope element retrieval to project and branch.
* Validate element type consistency.
* Fetch tags separately if end system stores them independently.
* Do not over-fetch data if `expand` is not specified.
* Convert all data strictly into `MbseElement` format.
* Ensure consistent timestamp formatting (ISO-8601).

***

### Design Rationale

This API provides controlled and expandable element retrieval.

By:

* Supporting selective expansion
* Supporting property/tag filtering
* Maintaining strict scoping

The API ensures performance efficiency and predictable synchronization behavior across heterogeneous MBSE systems.


---

# 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/element-apis/element-get.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.