Holarch

Reference

API and MCP

Read and change projects from scripts with a personal access token (REST API at /api/v1), and let AI tools read them and propose changes you review (MCP at /mcp); scopes, project lists, the organization switch, limits and examples.

How to use it →

On this page
  1. Concepts
  2. How to use it
    1. Create a token
    2. Read a project with curl
    3. Create and relate entities
    4. Connect Claude Code (MCP)
    5. Use Holarch with Claude
    6. Connect an AI app from Holarch
    7. Connect Holarch to Claude
    8. Ask Claude about Holarch
    9. Worked example: the CubeSat EO-1 demo
    10. Tips
  3. Personal access tokens
  4. REST API reference
    1. Values
    2. What a change also does
    3. Test results
  5. MCP reference
  6. Connected apps (OAuth)
  7. Proposals from AI clients
  8. Change requests
  9. Product lines
  10. Organizations
  11. Limits
  12. Messages
  13. Related pages

Holarch has a REST API and an MCP endpoint on Holarch servers (hosted or self-hosted), not in the desktop app. Both use a personal access token that you create under Account Settings → API tokens. A token acts as you: it reads and changes the projects you are a member of, within your role in each project.

  • REST API: https://app.holarch.app/api/v1/ for scripts, exports, imports and dashboards.
  • MCP: https://app.holarch.app/mcp for AI tools that speak the Model Context Protocol, such as Claude. Your own AI client reads the model and proposes changes; Holarch does not run or pay for that AI. An AI app can also connect with sign-in instead of a token: you approve it on a Holarch page (see Connect Holarch to Claude).

Plans: the API and MCP come with the Individual and Team plans and the Individual trial. On the Free plan they are available with a verified academic email address and to members of an active class organization, the same accounts that keep AI (Plans and limits). On other Free accounts, Account Settings → API tokens shows how to start the trial or choose a plan instead of the New token form, and connecting an AI app shows the same offer. Tokens and connected apps that an account already has are kept: their requests are refused with 403 plan-api until the account's plan includes the API and MCP again, and then they work without changes.

Changes from AI clients arrive as a proposal you review in Holarch (see Proposals from AI clients); nothing changes until you apply it. Changes through the REST API are written like edits in the app: everyone with the project open sees them at once, they are recorded in the project's history under your name, and they are part of the project's versions. The API works on the hosted service only.

Concepts

  • Token: a secret that starts with hol_. Holarch stores only a fingerprint of it and shows the token once, when you create it.
  • Access: Read only tokens read; Read and write tokens also create, change and delete. Your project role still applies: as a viewer or reviewer you only read, also with a read-and-write token.
  • Projects: a token works for all your projects, or only for the projects you select when you create it.
  • Expiry: in 30 days, 90 days, 1 year, or never.
  • Organization switch: an org admin can turn API access off for the organization's projects. Every token is then refused there with the code org-policy.

How to use it

Create a token

  1. Open the account button (your initials) → Account Settings → API tokens.
  2. Under New token, enter a Name that says what uses it, such as Claude Code or nightly export.
  3. Choose Access (Read only or Read and write), Expires and Projects (All your projects or Selected projects, then tick them).
  4. Click Create Token. The dialog Token Created shows the token with a Copy button, a curl example and the command to connect Claude Code.
  5. Copy the token now. Holarch shows it only once; an email “A Holarch API token was created” tells you about every new token.

The list shows each token's name, the first characters (hol_abcd…), access, projects, expiry and last use. Revoke ends a token's access at once.

Read a project with curl

curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
curl -H "Authorization: Bearer hol_…" "https://app.holarch.app/api/v1/projects/<project>/entities?class=Requirement&limit=50"

The first call lists your projects with their ids. The second lists the project's requirements, sorted by number.

Create and relate entities

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"class": "Requirement", "name": "Report thickness", "number": "SR.2",
       "description": "The system shall report the ice thickness.",
       "relationships": [{"relation": "satisfied by", "target": "<asset id>"}]}' \
  https://app.holarch.app/api/v1/projects/<project>/entities

The answer is the new entity with its id, attributes (a new requirement starts as Draft) and relationships.

Connect Claude Code (MCP)

  1. Create a token with the access the tool needs.
  2. Run:
claude mcp add --transport http holarch https://app.holarch.app/mcp --header "Authorization: Bearer hol_…"
  1. Ask, for example, “List my Holarch projects”, “Which requirements in the Lake Ice project have no verifying test case?” or “Propose a test case that verifies SR.2”.
  2. When the tool has sent its proposal, review it in Holarch: ✦ AI ▾ → Review “<title>”…, or the notification under the bell.

Other MCP clients that support remote servers over HTTP with a header work the same way. A client that runs only local servers can use a bridge such as mcp-remote:

npx mcp-remote https://app.holarch.app/mcp --header "Authorization: Bearer hol_…"

Use Holarch with Claude

Ways to connect Claude to Holarch:

Claude appHowStatus
Claude on the web, Desktop and mobileClaude's connector directory: Customize → Connectors → Browse, search for Holarch, click Connect, then sign in to Holarch and click Allow (below)Available
Claude on the web, Desktop and mobileA custom connector with the address https://app.holarch.app/mcp: you sign in to Holarch and approve it (below)Available
Claude Codeclaude mcp add --transport http holarch https://app.holarch.app/mcp, then sign in and approve; or the token command aboveAvailable
Claude CodeThe Holarch plugin: the connection plus skills to review requirements, find gaps, draft tests, summarize for a review, trace impact and propose decompositionsAvailable soon
Claude DesktopThe Holarch desktop extension: install the file and paste your tokenAvailable soon

With every method, Claude's changes arrive in Holarch as a proposal you review.

Connect an AI app from Holarch

Account Settings → API tokens → Connect an AI App… (or ⌘K / Ctrl+K → Connect an AI App…) walks you through connecting an app. Choose the app; the dialog shows its steps with the server's address and the commands ready to copy:

AppWhat the dialog gives you
Claude (web, Desktop and mobile)The connector-directory steps (Customize → Connectors → Browse, search for Holarch, Connect) with Open Claude Connectors; below them, the custom-connector steps with the address https://app.holarch.app/mcp to copy
Claude Codeclaude mcp add --transport http holarch https://app.holarch.app/mcp to copy, then /mcp → holarch → Authenticate
Other appThe address for any client that supports remote (HTTP) MCP servers. For an app that only sends a fixed header, Create Token makes a token in the dialog and shows it once, with the header and an mcp-remote command

Each app then signs in on Holarch's page, where you choose the access and projects and click Allow (below). The one-click links and commands contain only the address, never a token. When you are done, the app is listed under Connected apps, where Disconnect ends its access.

On a plan without the API and MCP, the dialog shows how to start the trial or choose a plan instead of the steps.

Connect Holarch to Claude

Connect with sign-in, without creating or pasting a token:

  1. In Claude, open Customize → Connectors → Browse and search for Holarch. Or add it yourself: in Customize → Connectors, click + Add, then Add custom connector, name it Holarch and enter https://app.holarch.app/mcp. In Claude Code, run claude mcp add --transport http holarch https://app.holarch.app/mcp, then /mcp → Authenticate.
  2. Click Connect. A Holarch page opens in your browser. Sign in if you are not signed in (password, passkey, Google or Microsoft, and the second step if you turned it on).
  3. Holarch shows Connect Claude to Holarch with the app's name and the address it returns you to (claude.ai; for Claude Code, your own computer). Choose:
    • Access: Read and propose changes or Read only.
    • Projects: All your projects or Chosen projects.
    • Ends: in 1 year (the default), 30 days or 90 days. A connection lasts one year at most; to keep using the app after that, connect it again.
  4. Click Allow. Your browser returns to Claude, which is now connected. Deny returns without connecting.

For an app that runs on your computer, such as Claude Code, Holarch warns you: allow it only if you started connecting it yourself.

The app's name is the one the app chose for itself; Holarch does not verify it, and the page says so. Check the address it returns you to. Holarch refuses apps that name themselves after Holarch.

The connection acts as you, like a token with the same choices: your project roles apply, the organization switch applies, and in an organization that requires two-step sign-in it works only while yours is on. Connecting the same app again replaces its earlier connection. You get an email when an app is connected.

End date: Account Settings → API tokens → Connected apps shows when each connection ends. Refreshing tokens does not move it.

Disconnect: Account Settings → API tokens → Connected apps → Disconnect. Its access ends at once. Connected apps are not listed among your personal tokens.

When access ends by itself: a password reset (Forgot your password?), Sign Out Everywhere, and an administrator's Sign Out Everywhere or Reset Two-Step Sign-In disconnect every connected app and revoke every personal access token of the account at once; the email about it gives the numbers. A password change while signed in leaves them working, unless you tick Also disconnect apps and revoke API tokens. Sign Out Other Devices leaves them working.

Ask Claude about Holarch

Once Claude is connected (with a token or with sign-in, above), it can answer questions about Holarch itself, not only about your projects. It searches the published Docs and Help and links to the page it used.

  • Ask, for example, “How do I export the traceability matrix to Excel?”, “Can Holarch import ReqIF?”, “What does the Free plan include?” or “Which diagram types does Holarch have?”.
  • Claude reads the current Docs from holarch.app each time it asks, so its answers follow the latest release. If holarch.app cannot be reached, it uses the copy of the Docs that comes with Holarch and says the answer may be slightly out of date.
  • For things Holarch does not do, Claude says “not yet” instead of guessing: it checks the list of what Holarch does and does not do (get_capabilities).
  • The connection still needs your token or your sign-in. Read-only access is enough, and no project access is needed for these questions.

The tools appear in Claude without an update. A conversation that was already open keeps its earlier list of tools: start a new conversation, or reconnect the connector, to see the new tools.

Worked example: the CubeSat EO-1 demo

  1. Create a read-only token for the CubeSat project.
  2. GET /api/v1/projects/<project>/model-checks?class=Requirement lists the requirement findings, such as Requirement.10 Leaf requirements with no verifying test case, with the entity and the related items.
  3. GET /api/v1/projects/<project>/quality scores every requirement on the nine quality attributes, with the findings per attribute.
  4. With a read-and-write token, a script adds the missing test case with POST /api/v1/projects/<project>/entities and the body {"class": "Test Case", "name": "Thermal vacuum test", "relationships": [{"relation": "verifies", "target": "<requirement id>"}]}. Model Checks then no longer list the requirement.

Tips

  • Give each script or tool its own token, read only where it only reads, and limited to the projects it needs.
  • Keep tokens out of shared files and source code. Anyone with a token acts as you.
  • Ask the AI tool to read the schema first (get_schema): it lists the class, attribute, relation and label names the project uses.
  • Model Checks and quality results through the API are returned, not stored. The app's Quality page stores quality results in the requirements.

Personal access tokens

FieldValues
NameUp to 100 characters
AccessRead only, Read and write
ExpiresIn 30 days, 90 days, 1 year, or never
ProjectsAll your projects, or selected projects
  • An account has at most 20 tokens, and creates at most 20 an hour.
  • A token stops working when it is revoked, when it expires, and when its account is disabled, unverified or deleted. On a plan without the API and MCP it is refused (403 plan-api) but kept, and works again after an upgrade. Removing you from a project ends the token's access to that project at once.
  • Send the token in the header Authorization: Bearer hol_…. Requests never use your browser's sign-in, and a token does not work on the app's own pages or routes.
  • Each new token is recorded in the audit log and announced by email; the token itself is never logged or mailed.
  • Revoked and expired tokens are deleted 90 days after they stopped working. Deleting your account deletes your tokens and your AI clients' proposals at once.

REST API reference

Base address: https://app.holarch.app/api/v1. Answers are JSON. The machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1).

Method and pathWhat it does
GET /meThe token's account, access, projects and expiry
GET /projectsYour projects: id, name, role, item count, last change, whether API access is allowed, link
GET /projects/<project>Name, description, your role, item count and limit, items per class, number of documents
GET /projects/<project>/schemaClasses with attributes (type, choices), allowed relations and labels; relations with their inverse
GET /projects/<project>/entitiesSearch: class, label, q (text in name, number, description or class), limit (1–500, default 100), offset
POST /projects/<project>/entitiesCreate: class, name, number, description, labels, attributes, relationships, appliesTo, effectivity
GET /projects/<project>/entities/<id>One entity: attributes by name, labels, relationships with direction and the other entity
PATCH /projects/<project>/entities/<id>Change name, number, description, labels, attributes, appliesTo or effectivity; fields not sent stay
DELETE /projects/<project>/entities/<id>Move the entity and its relationships to the project's Trash
POST /projects/<project>/test-resultsRecord results from a test system on existing test cases, as Test Center → Import Results… does: results (each testCase, status, optional actualResult, testedBy, testDate, configuration, testArticle), optional defaults testedBy, testDate, timeZone, configuration, testArticle, and source. Answers recorded and skipped (Test results)
POST /projects/<project>/relationshipsRelate: source, relation (named from the source), target, optional attributes
DELETE /projects/<project>/relationships/<id>Remove a relationship
GET /projects/<project>/external-linksLinks from this project's items to items in other projects, ids only: id, from, relation, to (project, item); ?from=<id> for one item. An entity read also lists them as externalLinks
POST /projects/<project>/external-linksLink an item to an item in another project: source, relation, to (project, item). Team plan
DELETE /projects/<project>/external-links/<id>Remove such a link
POST /projects/<project>/resolveName, number, class and status of linked items: refs (at most 500 {project, item}), read with the token's own access. A project the token cannot use answers no-access, the same as one that does not exist
GET /program-mapThe Program Map: projects the token can use and the links between them, counted per pair of projects and relation, with deleted targets; links into projects the token cannot use are only counted (hidden). from, unlinked, org
GET /projects/<project>/items/<item>/traceAn item's chain of links through other projects, steps 1–6 (default 3), at most 500 items
GET /projects/<project>/documentsDocuments with type and number of sections
GET /projects/<project>/documents/<id>The document's sections in document order, with numbers and plain text
GET /projects/<project>/model-checksModel Checks with the project's rule settings and rule sets; class (Custom for rule sets), rule, limit, offset; in a SysML v2 project, the project's rule sets and the product-line rule ProductLine.3 (configurations that break a rule or are incomplete). Not yet: the built-in Product line rules (ProductLine.1–9), which Model Checks in the app runs
GET /projects/<project>/qualityRequirement quality check; ids (comma-separated) or every requirement. Per requirement: score, criteria (attribute name → true, false or null = not checked) and issues
GET /projects/<project>/versionsSaved versions the project's plan keeps
GET /projects/<project>/configurationsThe product line: features, rules and configurations with their selection and verdict (Product lines)
GET /projects/<project>/spreadsheetsSpreadsheets with their sheets: id, name, used rows and columns, filled cells
GET /projects/<project>/spreadsheets/<id>/rangeComputed values of a range: ref (A1 style, such as B2:D20 or 'Sheet 2'!A:C), sheet (name or id when ref names none), formulas=true for each cell's formula. Clipped to the used cells, blank cells are null, at most 10,000 cells (truncated says when more were asked)
POST /projects/<project>/spreadsheets/<id>/cellsWrite cells as one change: sheet (default the first), cells (at most 1,000 {ref, value}). A value is a number, text, true/false, null (clear) or a formula starting with =; send numbers as JSON numbers. A formula that does not parse refuses the whole write and names the cell. The spreadsheet cell limits apply
POST /projects/<project>/proposal/changesAdd a change to your open proposal instead of changing the project: op (create, update, delete, relate, unrelate, result) with the fields of the matching call above (entity for update and delete, relationship for unrelate; for result, one result's fields of …/test-results, recorded with its run log entry when the proposal is applied). A create answers ref (new:1, new:2, …), which later changes in the same proposal use as an id
GET /projects/<project>/proposalThe open proposal (or ?id=<id>) with its status and changes
POST /projects/<project>/proposalSend the open proposal for review: title, summary; answers the review link
DELETE /projects/<project>/proposalDrop the open proposal before it is sent
GET /projects/<project>/change-requestsThe project's change requests, newest first: id, ref (CR-12), title, status, author, staged changes and, with branch review on, the number of changes made in the request; ?status= for one status
GET /projects/<project>/change-requests/<CR-12 or id>One change request: reason, status, votes, staged changes, and for a request worked on as a draft its changes field by field and its conflicts with the live model now (Change requests)
POST /projects/<project>/change-requestsCreate a Draft change request: title, reason, items (Team plan, branch review on)
POST /projects/<project>/change-requests/<CR-12>/changesWrite a change into the request's draft (as …/proposal/changes)
POST /projects/<project>/change-requests/<CR-12>/submitSend the request for review (note)
DELETE /projects/<project>/change-requests/<CR-12>Withdraw the request (its author or an owner; Draft or Rejected)

The reads of the model (/projects/<project>, entities, documents, Model Checks, quality and the SysML v2 reads) take ?change_request=CR-12 to read the model as that change request would make it. In LML projects they also take ?configuration=CFG-2 and ?effectivity=sn:23 to read the model as one configuration of a product line shows it (Product lines).

Method and pathWhat it does
GET /cli/entitlementWhether the token's account may run the holarch command line tool

Values

  • Names: classes, labels, relations and attributes are given by name, case-insensitive (Requirement, satisfied by, Status). Numeric ids also work, including the earlier numbers of built-in items; prefer names.
  • Attributes: an object of attribute name → value, checked against the attribute's type: numbers for number and percentage attributes, true/false for yes/no, one of the choices for lists, text otherwise. null removes a value. File attributes cannot be set through the API.
  • Descriptions: plain text, or rich text as HTML. Rich text is cleaned with the same rules as in the app. Answers give the plain text as description; a single entity's answer also has the stored rich text as descriptionHtml.
  • Live values in rich text show the cited item's value in the plain text. A live value that shows Global ID gives the entity id (for example e42); live values that cite an item by an earlier I_… value still find it.
  • Quality criteria (quality, quality_check): true (met), false (not met) or null (not checked). A requirement that is not in English gets null for Unambiguous until its wording is checked with AI in the app or rated by hand; score then counts only the checked criteria (Requirements in other languages).
  • Relationships: only the pairs the schema allows (the class's relations in the schema). Relating two entities again returns the existing relationship with "created": false.
  • Feature attributes: the attributes, labels and classes that Holarch features add to LML (such as Test Case Tested By and Test Date, Risk Owner, the Hazard and Failure Mode classes) are in every project's schema, also in a project nobody has opened in the app yet. The first change through the API stores them in the project, as opening it in the app does.

What a change also does

Changes run the same follow-ups as in the app:

  • A new requirement starts with the status Draft.
  • Setting a requirement's Status records who set it and when, as on the Quality and Approvals pages.
  • Changing a requirement's name or description marks its downstream links for review (decomposed by, derived by, refined by, satisfied by, verified by, traced to), marks stored quality results stale, and sends an Approved requirement back to In Review. Changing Priority, Criticality or a number also marks the links for review; changing a set Verification Method or Level marks only the verified by links.
  • Locked entities refuse changes (409 locked); unlock them in the app.
  • Configuration control: when the project requires change requests (Configuration control), changes to approved requirements and to items in the latest project baseline are refused with 409 change-control: editing, deleting, and adding or removing their relationships and external links. The message names the item: “SR.1 Detect ice is under configuration control (approved). Propose the change in a change request: Control & Reviews → Change Requests.” Setting the Status stays open, as in the app. Other items change directly. AI clients get the same refusal from the write tool, so a proposal never holds such a change.

Test results

POST /projects/<project>/test-results records results from a test system, such as a CI pipeline, the way Verification → Test Center → Import Results… records a results file (Import results from another test system). Each recorded result:

  • sets the test case's Status, Tested By, Test Date, Configuration and Test Article, and Actual Result when the result gives one (without one, the Actual Result stays);
  • adds an entry to the test case's run log with the status, tester, date, configuration, test article, actual result and source (default API).

All results of a request are one change, recorded under your name in the project's history. Nothing is created.

  • Test case: testCase is the test case's id, number (TC-14) or name, matched in that order and regardless of case.
  • Status: Passed, Failed, Blocked, In Progress or Not Run, or a test tool's word: pass, ok and success record Passed; fail, failure and error record Failed.
  • Defaults: a result without testedBy, testDate, configuration or testArticle takes the request's. Without one, Tested By is your account name and Test Date is the time of the request in timeZone (such as America/Chicago; UTC when none is given). Dates are YYYY-MM-DD or YYYY-MM-DDTHH:MM, kept as written.
  • Several results for one test case: the last one that can be recorded is recorded; the earlier ones are skipped as superseded. A result that is skipped for its own reason (for example skipped or bad-value) replaces nothing and is reported with that reason.

Results that cannot be recorded are listed in skipped, each with testCase, code and reason; the others are still recorded:

CodeMeaning
not-foundNo test case has that id, number or name
ambiguousSeveral test cases have that number or name; name it by its id
skippedThe status says the test was skipped
bad-valueThe status is not one Holarch knows
has-childrenThe test case has child test cases; its status rolls up from them
lockedThe test case is locked
change-controlThe test case is under configuration control; record the result in the app through a change request
supersededA later result in the request names the same test case and is recorded
curl -X POST https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/test-results \
  -H "Authorization: Bearer $HOLARCH_TOKEN" -H "Content-Type: application/json" \
  -d '{"source": "results.xml", "configuration": "Build 241", "timeZone": "America/Chicago",
       "results": [{"testCase": "TC-14", "status": "pass"},
                   {"testCase": "TC-04", "status": "fail", "actualResult": "0.12 degrees on 2 of 20 targets"}]}'

The answer lists each recorded test case with its status before and after, Tested By and Test Date. In a product line, results recorded this way are not tied to a configuration; to record a configuration's results, use Import Results… or Run Suite in the app.

MCP reference

The endpoint https://app.holarch.app/mcp speaks the Model Context Protocol over Streamable HTTP (protocol versions 2025-03-26 and 2025-06-18) with the same tokens. It answers each request with JSON; it has no event stream and no sessions.

ToolAccessWhat it does
list_projectsReadYour projects and roles
get_projectReadA project's summary
get_schemaReadClasses, attributes, relations and labels
search_entitiesReadSearch by class, label and text
get_entityReadOne entity with its relationships
list_external_linksReadLinks to items in other projects, ids only
resolve_external_itemsReadNames of linked items in other projects, with your access; a project with regulated-data markings answers withheld
program_mapReadYour projects and the links between them; links into projects you cannot open are only counted
trace_chainReadAn item's chain of links through other projects, 1–6 steps; a project with regulated-data markings answers withheld
list_documentsReadThe project's documents
get_documentReadA document's sections in order
run_model_checksReadModel Checks, optionally for one class or rule
quality_checkReadThe requirement quality check
list_diagramsReadThe project's diagrams with their type, title and root item
get_diagramReadOne diagram's items and the relationships among them (not its layout)
get_matrixReadThe RVTM (method, level, success criteria, verifying test cases, status, stages and events, deviations and closure) or a traceability matrix (rows of one class, links to another, optionally one relation or gaps only) as rows, paged
get_registerReadThe formal program's records as rows, paged: issues (issues, actions and nonconformances with status, assignee, due date, overdue and sources), deviations, nonconformances, rids, gates (gate records with outcome and open actions) or compliance (a customer specification's statement of compliance)
search_docsReadSearch the published Docs and Help; each match has a title, a short excerpt and its holarch.app address
get_doc_pageReadOne Docs page or Help topic, or one section of it, as text with its address
get_capabilitiesReadWhat Holarch does and does not do yet, the project types, and the plans with their limits
list_spreadsheetsReadThe project's spreadsheets and their sheets
read_rangeReadComputed values (and optionally formulas) of a spreadsheet range, A1 style
get_proposalReadThe open proposal, or one by id, with its status and changes
list_proposalsReadYour recent proposals and their status
create_entityRead and writePropose an entity, optionally with relationships; returns a reference such as new:1
update_entityRead and writePropose a change of an entity
relateRead and writePropose a relationship (ends can be new:<n>)
unrelateRead and writePropose removing a relationship
delete_entityRead and writePropose moving an entity to the Trash
write_cellsRead and writePropose cell values or formulas on one spreadsheet sheet; formulas are checked now. The review shows each cell before and after
record_test_resultsRead and writePropose test results, one change per result; applied, each one is recorded as by …/test-results (Test results)
propose_changesRead and writeSend the proposal for review, with a title and summary
discard_proposalRead and writeDrop the open proposal before it is sent
list_configurationsReadThe product line: features, rules and configurations with their selection, verdict and effectivity
list_change_requestsReadThe project's change requests with their number, title, status and counts
get_change_requestReadOne change request: reason, status, votes, staged changes, its changes and its conflicts with the live model

The model reads (get_project, search_entities, get_entity, documents, diagrams, matrices, registers, checks and the SysML v2 reads) take an optional change_request to read the model as that request would make it. The write tools and propose_changes take one to send the proposal into a draft change request (Change requests).

In LML projects the model reads also take configuration and effectivity, the write tools take configuration (in record_test_results, configuration is the Configuration attribute: the build or version under test), and create_entity and update_entity take appliesTo and effectivity (Product lines).

search_docs, get_doc_page and get_capabilities need a token or a sign-in like the other tools, but no project. They read the Docs as published on holarch.app at the time of the question; when the site cannot be reached, the answer comes from the copy that comes with Holarch and says so.

A read-only token lists only the read tools. New read tools need no new approval: they come with the access you already gave. A client lists the tools when it connects, so an open conversation shows new tools only after you start a new one or reconnect. A refused change (no access, unknown class, a relationship the schema does not allow) comes back as a tool result with the app's message, so the AI tool can explain it.

AI permissions apply to MCP tool calls as to Holarch's own AI (see AI permissions): read tools need Questions about the project, write and proposal tools need Suggestions and changes, and search_docs, get_doc_page and get_capabilities need Help and how-to. The switches of the project's organization, its owners (for a project outside organizations), the installation and your account all apply. A refused call is a tool result with isError, code ai-kind, the kind and level, and the same text as in the app, for example “Changes by AI are turned off for this organization by its administrator.” REST API calls under /api/v1 are not AI requests and are not limited by AI permissions.

Connected apps (OAuth)

For developers of MCP clients. Holarch is the OAuth 2.1 authorization server for its MCP endpoint, as the MCP authorization specification describes:

  • Discovery: a request to /mcp without a token gets 401 with WWW-Authenticate: Bearer resource_metadata="https://app.holarch.app/.well-known/oauth-protected-resource", scope="holarch:read holarch:write". The protected resource metadata names the resource https://app.holarch.app/mcp and the authorization server https://app.holarch.app (/.well-known/oauth-authorization-server).
  • Clients: Client ID Metadata Documents (an https client id with a path) and Dynamic Client Registration at /oauth/register. Public clients only (token_endpoint_auth_method: none).
  • Redirect URIs: https, or http on a loopback address of the user's own computer (RFC 8252). They must match exactly; loopback URIs match on any port.
  • Authorization: /oauth/authorize with response_type=code, PKCE S256 (required), state, scope and resource. The answer carries code, state and iss.
  • Scopes: holarch:read, holarch:write (propose changes) and offline_access. The person may grant read only when write was asked for.
  • Tokens: /oauth/token (form-encoded) for authorization_code and refresh_token. Access tokens start with hoa_ and last one hour; refresh tokens start with hor_, are replaced at every use, and a refresh token used twice ends the connection. A grant lasts at most 365 days from the person's approval; refresh tokens never outlive it. Codes are single use and expire after 60 seconds.
  • Audience: an access token works only at https://app.holarch.app/mcp; the REST API at /api/v1 refuses it. Send tokens in the Authorization header only.
  • Revocation: /oauth/revoke (RFC 7009). Revoking a refresh token ends the connection.

Proposals from AI clients

AI clients never change a project directly. Their write tools collect changes in one open proposal per token and project; nothing in the project changes. propose_changes sends it for review with a title and summary. Scripts work the same way through the REST proposal calls or the Python client.

  • Who reviews: the token's owner and the project's owners. They get a notification (“Name's API client proposes changes: title”), and the open project shows the proposal in the ✦ AI ▾ menu as Review “title”….
  • The review dialog: every change with a checkbox: creations with editable Name, Number and Description, changes with the current and the proposed values (text as a word diff), relationships, deletions. A warning names the account and token that sent it. Deletions, removed relationships and changes to approved, baselined or locked items start unticked. The Impact list shows what traces to the changed items, marked Affected or Check (Impact).
  • Test results (record_test_results, or op: result) show the attribute changes and that a run log entry is added. Applied, each sets the attributes and adds the run log entry as Import Results… does; a result that names no Test Date gets the time of the apply.
  • Apply Selected applies the ticked changes with your name in the history and the usual follow-ups (links to review, approvals), and a single Undo takes it all back. Changes whose items were deleted since are skipped with a note. Reject discards the proposal; Later keeps it waiting.
  • Permissions: applying needs the editor or owner role when you apply; viewers and reviewers can only reject. Plan limits and locks apply as for any edit.
  • Expiry and retention: a proposal expires 7 days after it was started. Applied, rejected and expired proposals are deleted 30 days later. The AI client sees its status (open, ready, applied, rejected, expired) with get_proposal and list_proposals.

Change requests

Scripts and AI clients read change requests and can send proposals into a draft one; a person always decides.

  • Read: list_change_requests and get_change_request (REST: GET …/change-requests, GET …/change-requests/CR-12). A request is named by its number (CR-12) or its id. The answer gives its status as the change request page shows it, the votes with their names, notes and whether they still count, and its staged changes. For a request worked on as a draft it also gives every change (item, relationship, diagram or SysML v2 element; added, changed or removed; each changed field with its value before and after) and its conflicts with the live model now: the items both sides changed in the same field, items one side deleted while the other changed them, and links to items deleted in the live model. Changes to different fields of one item are counted as merged; they apply without asking.
  • The model as a request makes it: change_request on the read tools (REST: ?change_request=CR-12) reads the model with the request's draft changes in place. Without it, reads show the live model. Staged changes made with Add Change ▾ are listed by get_change_request, not applied to these reads.
  • Proposals into a draft: name the request with change_request on a write tool or on propose_changes (REST: in the body of …/proposal/changes or …/proposal). The proposal's changes are then checked against the request's model, and after review in Holarch they are applied into that change request instead of the live model. A proposal has one target: name it once; a proposal that already holds changes for the live model or another request is refused (409 cr-mismatch). The request must be in Draft or Rejected, the project must have branch review on (Change Requests → Settings), and its owner's plan must be Team (self-hosted servers include it).
  • Write into a change request (REST): create one with POST …/change-requests (title, reason, items), then add change_request=CR-12 to the entity and relationship writes (query or body) or POST …/change-requests/CR-12/changes with a change as for proposals (SysML v2 projects: package text or element edits, checked by the language core first). The change goes into the request's draft, not the live model, recorded under your account "via API (<token name>)". POST …/change-requests/CR-12/submit sends it for review; DELETE …/change-requests/CR-12 withdraws it (its author or an owner, while Draft or Rejected). A write without change_request changes the live model as before, except items under configuration control, which change only through a change request. Writes into change requests need the Team plan (academic and class accounts included) and branch review on; MCP stays proposal-only.
  • Never through the API or MCP: voting, choosing between conflicting versions and applying a change request. These need a person in Holarch and, on the hosted service, the password check; the REST paths answer 405 person-only, and MCP has no such tools.
  • Branch review off: change requests are still listed and read (status, votes, staged changes; no draft changes), reads with change_request show the live model, and proposals naming a request are refused (409 branch-review-off).

Product lines

Scripts and AI clients read a product line (features and configurations) and the model as one configuration shows it, and change it like any other data. This works in LML projects.

  • The product line: GET …/configurations (MCP list_configurations) gives the features (number, name, kind Mandatory or Optional, group of their children: any, one (choose one) or some (choose at least one), parent, constraint, requires, excludes), the rules as lines (“F-4 requires F-3”) and the configurations: number, name, status (Draft, Released, Retired), the features they select (selects), their effective selection (selection: the selected features, their parents and the Mandatory children), valid and verdict (kind valid, breaks or incomplete, with the reason as text, such as “Breaks: Wallbox requires Large pack.”), effectivity and owner.
  • Reading all configurations: without configuration, entities and relationships carry their product-line fields when they have them: appliesTo (the readable expression, such as F-3 and not F-5), appliesToIds (the stored form with item ids), effectivity (serials, from, until), values (each configuration's own values by its number and the attribute's name, such as {"CFG-2": {"Mass": 1520}}) and in (configurations that put the item in or took it out).
  • Reading one configuration: configuration names it by number (CFG-2), name or id. The answer holds only the items and relationships that apply to it, with its own values in place of the base values and no values block; entity lists also give each entity's attributes. The answer names the configuration in configuration. An item that does not apply answers 404 not-found. A test case shows only the configuration's own results: a result recorded without a configuration counts for none, so it is left out, and the test case's resultNote says "A result without a configuration (TC-1) does not count for CFG-2."
  • Effectivity point: effectivity=sn:23 (a serial number) or effectivity=date:2027-03-01 keeps only the items in effect then. It works with or without configuration; when the point is outside the configuration's own effectivity, the answer says so in note.
  • Applies To and effectivity fields: appliesTo is typed as in the app: feature and configuration numbers, names in quotes ("Wallbox"), config "Plug-in Hybrid", and, or, not and parentheses. "" or null means every configuration. effectivity is {"serials": "1-20, 25, 40-", "from": "2027-03-01", "until": "2028-01-01"} (until is the first day it no longer applies); null or {} clears it. Serial ranges are stored sorted and merged (1-20,25,40-). An expression or range the app would not accept is refused with its message, such as “No feature or configuration named “F-9”. Choose one from the list, or create the feature first.”
  • Writing in a configuration: add configuration to a write (REST: query or body; MCP: the write tools; Python: configuration=). The change is made as in that configuration's view in the app:
    • a new entity applies to that configuration (when the product line has other configurations); a new relationship gets that configuration as its Applies To when its ends are also together in another configuration;
    • Name, Number, Labels, Applies To and effectivity are shared by every configuration; a description or attribute becomes the configuration's own value while other configurations share the entity, and sending the base value removes the own value; an entity only that configuration has gets base values; a test case's results (Status, Actual Result, Tested By, Test Date, Configuration, Test Article, Test Evidence) are always the configuration's own;
    • a delete or relationship removal takes the item out of that configuration when other configurations keep it ("removedFrom": "CFG-2"; nothing goes to the Trash; its children stay), and otherwise deletes it as usual;
    • an entity or relationship that is not in the configuration answers 404 not-in-configuration; a Retired configuration is read-only (409 retired-configuration). An AI client's proposal made this way names its configurations, and the review dialog says “Apply in CFG-2: new items apply to CFG-2; changed values become CFG-2’s.” Applying it gives the same result in every view.
  • Plans: reading a project as a configuration works on every plan. Creating features or configurations and writing Applies To, effectivity or configuration values need the project owner's Individual or Team plan (academic and class accounts included); without it they are refused with 403 plan-limit (limit: product-line), while clearing them and other changes still work. Setting a configuration's Owner needs Team (limit: product-line-team). A downgrade deletes nothing.

Organizations

Org admins turn API access on or off under Organization Settings with Allow API and MCP access to this organization's projects. Off refuses every API and MCP request for the organization's projects, also with members' own tokens. The change is recorded in the audit log. See Organization Settings.

Limits

  • 600 requests a minute and 120 changes a minute per account; over that, the answer is 429 with Retry-After. The limits are shared by all of your tokens and connected apps, across the REST API and MCP, so a second token does not add to them. Reads through the Systems Modeling API (GET /api/v1/sysml/…) count separately, up to 6,000 a minute, so clients that read a model one element at a time (the OMG API cookbook, the Pilot Implementation) can walk large models.
  • Request bodies up to 1 MB; up to 500 entities per page, 5,000 Model Checks findings per page.
  • Plan limits apply as in the app: a change that adds items over the project's limit is refused with 403 plan-limit.
  • Not available yet: creating, renaming or sharing projects, diagrams, comments, attachments, baselines, webhooks, and OAuth sign-in for the REST API (/api/v1): connected apps use MCP only.

Messages

CodeStatusMeaning
token-required401No Authorization: Bearer header
token-invalid401The token is wrong, revoked or expired, or its account cannot sign in
read-only-token403A change with a read-only token
ai-kind403 (MCP: a tool result)An MCP tool call that the AI permissions turn off; kind (help, read, changes) and level (installation, organization, project, owner, account) say which switch and who turned it off
forbidden403Your role in the project does not allow the change
org-policy403The project's organization turned API access off
plan-api403The account's plan does not include the API and MCP (the Free plan without an academic email address or class organization). Start the Individual trial or choose a plan; the token works again
plan-cli403The account's plan does not include the holarch command line tool (the Free plan, also with an academic email address). Choose the Individual or Team plan
plan-limit403The change would go over the project's item limit, a proposal or write names a change request in a project without the Team plan (limit: branch-review), or it writes product-line data without the owner's Individual or Team plan (limit: product-line; configuration owners: product-line-team)
person-only405Voting on, resolving or applying a change request through the API: do it in Holarch
branch-review-off409A proposal or write names a change request, but the project does not use change request drafts
cr-not-draft409The change request named by a proposal or a write is not in Draft or Rejected
cr-mismatch, cr-stale409The open proposal holds changes for another target, or its changes do not apply to the named change request; send or discard it first
not-found404No such project (or not yours), entity, relationship or document
locked409The entity is locked
change-control409The item is under configuration control (approved or in the latest baseline); propose the change in a change request in the app
unknown-configuration, bad-applies-to, bad-effectivity400The configuration, Applies To expression or effectivity is not one the project accepts; the message names the problem
not-in-configuration404The entity or relationship does not apply to the configuration the write names
retired-configuration409The configuration is Retired and read-only; copy it to make changes
rate-limited429Too many requests; wait the seconds in Retry-After
bad-request, unknown-class, unknown-attribute, bad-value, bad-relation400The request names something the project does not have, or a value of the wrong type