The API and MCP in SysML v2 Projects

Overview

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 projects work with the same REST API, MCP endpoint and personal access tokens as LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. projects. Scripts and AI tools read the model as elements and SysML text, check text before they change anything, and propose changes. Nothing in the model changes until a person reviews the proposal in Holarch and applies it.

Three ways in:

• REST API: https://app.holarch.app/api/v1/projects/<project>/… for scripts and dashboards. It reads elements, requirements, diagnostics and SysML text, and adds changes to a proposal.
• MCP: https://app.holarch.app/mcp for AI tools such as Claude. The SysML v2 tools read, search and check the model and propose changes.
• Systems Modeling API: https://app.holarch.app/api/v1/sysml/…, a read-only API in the shapes of the OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI. Systems Modeling API for other SysML v2 tools. It serves the project's current revision only.

Tokens, scopes, project lists, the organization switch, rate limits and connecting Claude are the same as for LML projects. See API and MCP for creating a token and connecting an AI tool.

Concepts

• Element: one item of the SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 model, such as a part definition, a port or a requirement. Each element has an id (a UUID). Wherever a route or tool asks for an id, a qualified name such as Vehicles::Car::powertrain also works.
• Brief: the short form of an element in lists: id, type (the metaclass, such as PartUsage), name, shortName, qualifiedName and owner.
• Top-level package: a package that is not inside another element. The SysML text of a project is one text per top-level package, plus one text for the elements outside packages.
• Diagnostic: a problem the language core finds, with code, severity (error or warning), elementId, element and args. Syntax diagnostics give line and col instead of an element.
• Proposal: the changes an API client or AI tool collects for review. One proposal is open per token and project. The client sends it for review with a title and summary.
• Paged replies: lists come in pages (limit, offset). Long SysML text comes in pages of lines (line, lines). A reply that left something out says truncated: true.

How to use it

Use the API when a script or AI tool needs the model: to report on requirements without satisfying or verifying elements, to check a team's SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. text against the model, or to let an AI tool draft model changes that an engineer then reviews.

Read a SysML v2 project with curl

1. Create a token under Account Settings → API tokens (see API and MCP).
2. List your projects:

curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects

SysML v2 projects have "language": "sysml2".

3. Get the model summary:

curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects/<project>/model

You see the element counts per metaclass, the top-level packages and the number of errors and warnings.

4. Find elements, for example every part definition:

curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/elements?type=part%20def&limit=100"

5. Read the SysML text of a package:

curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/sysml?root=Vehicles"

A long text ends with "truncated": true and "next": the line to ask for next with line.

Check SysML text before proposing it

1. Send the new text of a package to the check route:

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"root": "Vehicles", "text": "package Vehicles { … }"}' \
  https://app.holarch.app/api/v1/projects/<project>/sysml/check

2. Read the reply. ok is true when the text has no syntax errors. diagnostics lists syntax errors with line and col, and the errors the text would add to the model. changes is the number of model changes the text makes.

The check changes nothing. It needs only a read token.

Propose a change and apply it

A write token adds changes to the token's open proposal. The client then sends the proposal for review.

1. Add a change. Send either the complete new text of a package, or element edits:

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"edits": [{"op": "create", "kind": "attribute", "owner": "Vehicles::Car", "name": "range", "typedBy": ["LengthValue"]}]}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes

You get 201 with the proposal, the summary of the change and the elements it adds, changes and removes. A change that adds error diagnostics is refused (see Proposals in SysML v2 projects).

2. Add more changes the same way. Each change is checked against the model with the proposal's earlier changes applied.
3. Send the proposal for review:

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "Add range attribute", "summary": "Adds Car::range for the range requirement."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal

4. In Holarch, open the project, then open ✦ AI ▾ → Review “Add range attribute”… (or the notification under the bell).
5. Check the rows and click Apply Selected.

   The ticked changes are applied as one undo step, with your name in the history.

Connect an AI tool to a SysML v2 project

1. Connect the AI tool to https://app.holarch.app/mcp with a token or with sign-in (see API and MCP).
2. Ask about the model, for example “Summarize the Hybrid Car model in Holarch” or “Which requirements in the Hybrid Car project are not verified?”.

   The AI tool uses model_summary, list_elements, list_requirements and the other read tools.

3. Ask for a change, for example “Propose a range attribute on Car”.

   The AI tool reads the package with get_sysml, proposes text or element edits, and fixes any diagnostics the check returns.

4. Review the proposal in Holarch and click Apply Selected.

Worked example: the Hybrid Car demo

Create the demo with Manage Projects → Project Files ▾ → New Demo Project → Hybrid Car (SysML v2), then create a read-and-write token for it.

1. GET /api/v1/projects/<project>/model lists the top-level packages, among them Vehicles, HybridCarArchitecture and VehicleBehavior.
2. GET /api/v1/projects/<project>/elements?query=Engine&type=part%20def finds Vehicles::Engine.
3. GET /api/v1/projects/<project>/elements/Vehicles::Engine returns the part definition with its SysML text, its members (displacement, cylinders, maxPower, the ports fuelIn, output and ecu) and the usages typed by it.
4. GET /api/v1/projects/<project>/elements/Vehicles::Car/connections lists the interface driveShaft from powertrain.output to frontAxle.input.
5. GET /api/v1/projects/<project>/requirements?status=unverified lists the requirements that no verification case verifies, with their ids such as VR-4.1.
6. POST /api/v1/projects/<project>/proposal/changes with {"edits": [{"op": "update", "id": "Vehicles::Engine", "doc": "Gasoline engine of the hybrid powertrain."}]} adds the change to the proposal. POST /api/v1/projects/<project>/proposal with a title sends it.
7. In Holarch, ✦ AI ▾ → Review “…” shows Changed: with the part definition and the field doc, and the text diff of Vehicles. Apply Selected applies it.

Tips

• Read a package with get_sysml (or GET …/sysml?root=) before proposing new text for it. Elements left out of proposed text are removed.
• Prefer element edits for small changes. They change only the named elements and keep the rest of the package text as it is.
• Check text with check_sysml (or POST …/sysml/check) first. It returns the same diagnostics a proposal would be refused with.
• Name elements by qualified name in scripts. Ids stay the same when an element is renamed; qualified names do not.
• Give an AI tool a read-only token when it only answers questions about the model.

REST routes for SysML v2 projects

Base address: https://app.holarch.app/api/v1. Answers are JSON. /api/v1/openapi.json (OpenAPI 3.1) describes these routes with the others.

GET /projects and GET /projects/<project> also work for SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 projects. They give "language": "sysml2", and the project answer adds elements and types (element counts per metaclass).

The LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. entity routes (/entities, /relationships, /schema, Model Checks and the quality check) answer 409 wrong-project-type in a SysML v2 project. The SysML v2 routes answer the same in an LML project.

Values

• type: a metaclass such as PartUsage or RequirementDefinition, or a keyword as written in SysML text: part, part def, attribute, port, requirement, action, package and the other element keywords.
• owner, id, element, root: an id or a qualified name. root also takes the name of a top-level package. root must be a top-level package; to read one element's text, use element.
• Long values: a doc in a list is cut at 4,000 characters, a doc of a single element at 20,000, and an element's own SysML text at 16,000 characters.

MCP tools for SysML v2 projects

The MCP endpoint lists these tools next to the LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. tools. An AI tool finds SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 projects with list_projects (language: sysml2). Every tool takes project.

The proposal tools of LML projects work the same way here: propose_changes sends the proposal with a title and summary, discard_proposal drops it, and get_proposal and list_proposals show its status. A read-only token lists only the read tools.

Tool errors come back as a tool result with the message and the diagnostics, so the AI tool can fix its text and try again.

Element edits

Each edit in edits (MCP) or {"edits": […]} (REST) is an object with op:

• typedBy, specializes, subsets and redefines are lists of up to 20 names: ids, qualified names, or names as written in text (library names such as MassValue work).
• Later edits can name elements created earlier in the same call as new:1, new:2 … in the order they were created, for example as owner. The reply lists them under created with their new ids.
• Renaming an element also updates the references that named it by its old name.

Proposed text

• propose_sysml replaces the whole text of the package. Elements keep their ids where the text still declares them. Elements left out of the text are removed.
• The text must parse with nothing left unapplied. Text that does not change the model is refused (no-change).

Proposals in SysML v2 projects

Every proposed change is checked by the language core before it joins the proposal:

• The text parses without syntax errors, and element edits apply.
• The changed packages still print as SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. text and parse again.
• The change adds no error diagnostics to the model, such as unresolved names or type errors. Errors the model already had do not count.

A change that fails is refused with the diagnostics (up to 50) to fix. Nothing is stored. Warnings do not refuse a change.

Proposing needs a read-and-write token and the editor or owner role in the project. One proposal holds at most 200 changes and 8 MB.

Review a SysML v2 proposal

Open the project, then ✦ AI ▾ → Review “<title>”…. Each change is a row with a checkbox:

• Added, Changed and Removed list the elements, with the changed fields (the first 20 of each; “and n more” for the rest).
• A text diff, labelled with the package, shows the SysML text before and after.
• A change that removes elements is flagged and starts unticked.
• Open the SysML v2 model to apply this change. The model is not loaded; open a SysML v2 page of the project.
• The package is no longer in the model; skipped. The package was removed after the change was proposed.

Apply Selected syncs each text change again against the current model and keeps edits whose elements still exist. It checks the whole set and applies it as one undo step. Changes that no longer fit are skipped and named in a toast. Reject and Later work as for LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. proposals, and so do roles, expiry (7 days) and retention (see Proposals from AI clients).

Systems Modeling API (read only)

Other SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 tools read Holarch models through routes in the shapes of the OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI. Systems Modeling API (REST/HTTP). The base address is https://app.holarch.app/api/v1/sysml. It uses the same tokens; any project role can read.

• Projects: only SysML v2 projects are listed. A project's @id is a UUID this API gives it; the Holarch project id also works. The answer includes holarchId and url.
• Branches: each project has one branch, main.
• Commits: one commit, the head: the project's current revision. Its id changes with every saved change. Older commit ids answer 404; get the current one from the branch's head.
• Elements: the SysML v2 JSON of the model, the same format as the SysML v2 JSON export. Library elements are referenced by fixed ids.

List answers are JSON arrays. Element lists are paged with page[size] (default 100, at most 1000) and page[after] (the @id of the last element of the previous page). When more elements follow, the Link header gives the next page with rel="next".

Read a model's elements:

curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/sysml/projects/<projectId>/branches/main
curl -i -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/sysml/projects/<projectId>/commits/<head id>/elements?page[size]=500"

The Systems Modeling API in Holarch does not change models: there are no write routes, queries, diffs or older commits.

Messages

The codes of API and MCP apply. SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 routes and tools add:

Limits

Rate limits, request size and token rules are those of API and MCP.

Related pages

• API and MCP
• Getting Started with SysML v2 Projects
• The Text Editor and Browser
• Exchanging SysML v2 Models
• Requirements and Verification in SysML v2 Projects

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams.® and OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI.® are registered trademarks of Object Management Group, Inc. in the United States and other countries.