# Get Revisions ## API Name API Name: Revisions – Get *** ## Overview This API returns the list of revisions for a given project. MBSE Core uses this API for: * Polling revision history * Incremental synchronization * Identifying changes within a time window * Fetching revisions in chronological order Connector implementation **must**: * Sort revisions strictly based on `revisionTime` * Implement pagination even if the end system does not support it natively * Respect `pageNumber` and `pageSize` in all cases * Apply time filtering (`afterTime`, `beforeTime`) if supported by the end system * If time filtering is not supported, return complete data and allow MBSE Core to filter This API does **not** support `nextPageLink`. Pagination is strictly controlled using `pageNumber` and `pageSize`. *** ### API URI ```bash GET: /mbse/api/1.0/revisions ?projectId={projectId} &elementTypeIds={elementTypeIds} &branchId={branchId} &afterTime={afterTime} &beforeTime={beforeTime} &pageNumber={pageNumber} &pageSize={pageSize} &orderByDirection={ASC|DESC} ``` *** ### URI Parameters | Name | Mandatory | Type | Description | | ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | projectId | True | String | ID of the project for which revisions need to be fetched. | | elementTypeIds | True | List | List of element type IDs defined in `element-types` JSON configuration. Only revisions affecting these element types must be returned. | | branchId | False | String | ID of the branch from which revisions need to be retrieved. If omitted, default branch behavior of the end system should apply. | | afterTime | False | String | Time filter in format `YYYY-MM-dd'T'HH:mm:ss.SSSX`. Returns revisions updated strictly after this time. If end system does not support filtering, return full data and MBSE Core will filter. | | beforeTime | False | String | Time filter in format `YYYY-MM-dd'T'HH:mm:ss.SSSX`. Returns revisions updated strictly before this time. If end system does not support filtering, return full data and MBSE Core will filter. | | pageNumber | True | Integer | 0-based page index indicating which page of results to return. | | pageSize | True | Integer | Number of revisions to return per page. | | orderByDirection | True | String | Sorting direction based on `revisionTime`. Possible values: `ASC` (oldest first) or `DESC` (latest first). | *** ### Behavior Rules 1. Revisions must be sorted strictly by `revisionTime`. 2. `revisionTime` is the primary and authoritative sorting field. 3. Pagination is mandatory. Connector must: * Apply `pageNumber` and `pageSize` * Return only the requested page of results * Implement pagination logic even if the end system does not support it natively. 4. If both `afterTime` and `beforeTime` are provided, return revisions such that: afterTime < revisionTime < beforeTime 5. If the end system does not support: * Time filtering → return complete data and allow MBSE Core to filter. * Branch filtering → apply default branch behavior. 6. Only revisions affecting the provided `elementTypeIds` must be returned. 7. This API must not return element-level change details. It only returns revision metadata. *** ### Response Payload > Note: This is a sample response. Actual revision identifiers and metadata depend on the end system implementation. ```json { "revisions": [ { "revisionId": "rev_20260214_001", "parentRevisionId": "rev_20260213_004", "revisionTime": "2026-02-14T10:15:32.456Z", "author": "john.doe", "comment": "Updated Block definition and fixed constraint relations." }, { "revisionId": "rev_20260214_002", "parentRevisionId": "rev_20260214_001", "revisionTime": "2026-02-14T11:02:18.123Z", "author": "jane.smith", "comment": "Added new Requirement and linked to existing System Block." } ] } ``` *** ### Response Parameters | Name | Required | Type | Description | | --------- | -------- | ---- | -------------------------------------------------------------------------- | | revisions | True | List | List of revisions matching the provided filters and pagination parameters. | #### Revision Object | Name | Required | Type | Description | | ---------------- | -------- | ------ | -------------------------------------------------------------------------------------- | | revisionId | True | String | Unique identifier of the revision in the end system. | | parentRevisionId | False | String | Identifier of the parent revision. Used to represent revision lineage or commit chain. | | revisionTime | True | String | Timestamp when the revision was created. Format: `YYYY-MM-dd'T'HH:mm:ss.SSSX`. | | author | True | String | Username or identifier of the user who created the revision. | | comment | False | String | Revision message or comment associated with the revision. | *** ### Deterministic Ordering Requirement Connector must ensure deterministic ordering of revisions. If multiple revisions have identical `revisionTime`, connector should apply a secondary sort using `revisionId` to maintain consistent ordering across pages. *** ### Example Use Cases #### 1) Polling Revisions After a Given Time ```bash GET /mbse/api/1.0/revisions? projectId=123 &elementTypeIds=Block,Requirement &afterTime=2026-02-14T08:00:00.000Z &pageNumber=0 &pageSize=100 &orderByDirection=ASC ``` #### 2) Fetch Latest Revisions ```bash GET /mbse/api/1.0/revisions? projectId=123 &elementTypeIds=Block &pageNumber=0 &pageSize=50 &orderByDirection=DESC ``` *** ### Implementation Notes for Connector Developers * Revision granularity must align with the end system’s commit model. * If multiple element changes are grouped under one revision in the end system, return that revision only once. * Do not include element change details in this API. * Element-level changes must be retrieved using corresponding element-change APIs. * Pagination logic must be implemented at connector level if end system lacks native support. --- # 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-revisions.md?ask= ``` 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.