Reference
The Python Client
Read Holarch projects, search items and propose changes for review from Python scripts with the free holarch-api package; installation, sign-in, every method, proposals, errors and limits.
On this page
Overview
holarch-api is a small Python package for the Holarch REST API. It reads projects, items, documents and check results, searches, and proposes changes. It is free; the API itself comes with the plans that include it, and the package uses your personal access token.
Changes made through the package are always proposals: they collect on the server, and the project's owners review and apply them in Holarch, exactly like changes from AI clients, and a single Undo takes each applied proposal back. The package has no methods that change a project directly. Scripts that must write directly use the REST API's write calls.
Concepts
- Client: one token on one Holarch server. Every method sends one request (or one per page) and returns the API's JSON as Python dicts and lists.
- Typed answers: the package carries type information (
TypedDictshapes such asEntityandProjectSummary), so editors complete field names and type checkers such as mypy check them. Fields the server adds later simply appear in the dicts. - Proposal: your open proposal in one project. Each call adds one change;
send()hands the proposal to the project's owners for review. One token has at most one open proposal per project. - References: an entity created in a proposal does not exist yet.
create()returns a reference (new:1,new:2, …) that later changes in the same proposal use in place of an id.
How to use it
When and why
Use the client for scripts around a project: reports and exports in your own format, checks in a nightly job, imports from another tool that a person should review before they land. Because changes arrive as proposals, a script never surprises the team: the owners see every change before it is applied.
Install and sign in
- Install Python 3.9 or later, then the package:
python3 -m pip install holarch-api. It needs nothing besides Python. - In Holarch, open Account Settings → API tokens and create a token: Read only for scripts that only read, Read and write for scripts that propose changes. Limit it to the projects the script needs.
- Put the token in the
HOLARCH_API_KEYenvironment variable. - Check the connection:
from holarch_api import Client
c = Client()
print(c.me()["user"]["email"])
for p in c.projects():
print(p["id"], p["name"], p["role"])
Read a project
c = Client()
pid = "…" # the project id from c.projects()
info = c.project(pid) # name, description, items per class
for e in c.iter_entities(pid, cls="Requirement"):
print(e["number"], e["name"])
req = c.entity(pid, "…") # one entity with attributes and relationships
for r in req["relationships"]:
print(r["relation"], r["other"]["name"])
iter_entities fetches every match a page at a time; entities returns one page (entities, total, offset, limit). search(pid, "thermal") finds entities whose name, number, description or class contain the text.
Propose changes
- Start a proposal:
p = c.proposal(pid). - Add changes. Each call is checked by the server at once and fails with an error when the class, relation or attribute does not exist:
p = c.proposal(pid)
tc = p.create("Test Case", "Thermal vacuum test", description="Soak at -40 C for 8 hours.",
relationships=[("verifies", "…requirement id…")])
p.update("…", attributes={"Status": "Approved"})
p.relate(tc, "verifies", "…another requirement id…")
- Look at what is collected:
p.get()["changes"]. The project has not changed. - Send it:
view = p.send("Add a TVAC test", "Covers the two thermal requirements.").view["review"]is the link that opens the review in Holarch.
The owners get a notification and review the proposal from the ✦ AI ▾ menu; see Proposals from AI clients. To drop a proposal before it is sent, call p.discard(). To follow up later, c.get_proposal(pid, view["id"])["status"] is ready, applied, rejected or expired.
Worked example: the CubeSat EO-1 demo
- Create a read-only token for the CubeSat project and set
HOLARCH_API_KEY. - List the requirement findings of Model Checks:
c = Client()
pid = next(p["id"] for p in c.projects() if p["name"].startswith("CubeSat"))
checks = c.model_checks(pid, cls="Requirement")
print(checks["total"], "findings")
- Score the requirements:
c.quality(pid)["results"]lists each requirement with its score and findings. - With a read-and-write token, propose a test case for a requirement that has none, as in Propose changes, and send it. After an owner applies it, Model Checks no longer list the requirement.
SysML v2 projects
The same client reads SysML v2 projects: model(pid) (packages and counts), elements(pid, q=…, type=…), element(pid, "Vehicles::Engine"), requirements(pid), diagnostics(pid) and sysml_text(pid, root="Vehicles"). check_sysml(pid, text) checks text without proposing it. To propose a change, send the new text of a package with p.sysml_text(text, root="Vehicles"), or element edits with p.sysml_edits([...]); the engine checks each change and refuses one with errors. See The API and MCP in SysML v2 Projects.
Tips and good practice
- Read the schema first (
c.schema(pid)): it lists the class, attribute and relation names the project uses. - Give each script its own token, read only where it only reads.
- Collect related changes in one proposal and send it with a title and summary that say why: the reviewer sees the whole change at once.
- Keep tokens out of source files; the client reads
HOLARCH_API_KEYfor that reason.
Common mistakes
ApiErrorwith coderead-only-token: the token is read only; create a read-and-write token for proposals.ApiErrorwith codenot-foundon a project you can open in Holarch: the token is limited to other projects.- A created entity cannot be found with
entity(): it exists only in the proposal until an owner applies it.
Reference
Client
Client(token=None, server=None, timeout=30.0, retries=3). token defaults to HOLARCH_API_KEY, server to HOLARCH_SERVER or https://app.holarch.app. The server must be an https address.
| Method | Returns |
|---|---|
me() | The token's account, access and expiry |
projects() | Your projects: id, name, role, item count, language, link |
project(pid) | Name, description, role, item count, items per class, number of documents |
schema(pid) | Classes with attributes and allowed relations; relations |
entities(pid, cls=None, label=None, q=None, limit=100, offset=0) | One page of entities (at most 500) |
iter_entities(pid, cls=None, label=None, q=None, page_size=500) | Every matching entity |
search(pid, text, cls=None, limit=100) | Entities whose name, number, description or class contain the text |
entity(pid, id) | One entity with attributes, labels and relationships |
documents(pid) | Documents with type and number of sections |
document(pid, id) | One document with its sections in order, numbered, as plain text |
model_checks(pid, cls=None, rule=None, limit=500, offset=0) | Model Checks findings with a summary |
quality(pid, ids=None) | The requirement quality check, for the given requirements or all |
versions(pid) | Saved versions the project's plan keeps |
configurations(pid) | The product line: features, rules and configurations with selection, verdict and effectivity |
proposal(pid) | A Proposal for your open proposal in the project |
get_proposal(pid, proposal_id=None) | The open proposal, or one by id, with status and changes |
request(method, path, params=None, body=None) | Any other API call, relative to /api/v1 |
project, entities, iter_entities, search, entity, documents, document, model_checks and quality also take configuration= (a configuration's number, name or id) and effectivity= ("sn:23" or "date:2027-03-01") to read the model as one configuration of a product line shows it (Product lines).
Proposal
| Method | What it proposes |
|---|---|
create(cls, name, number=None, description=None, labels=None, attributes=None, relationships=None) | A new entity; relationships as (relation, target) pairs; returns its reference |
update(entity, name=None, number=None, description=None, labels=None, attributes=None) | Changed fields; fields left out stay, an attribute set to None loses its value |
delete(entity) | Moving the entity to the project's Trash |
relate(source, relation, target, attributes=None) | A new relationship, named from the source |
unrelate(relationship) | Removing a relationship (its id from entity()) |
get() | Nothing: returns the proposal with its changes |
send(title, summary="") | Nothing more: sends the proposal for review and returns it with the review link |
discard() | Nothing: drops the open proposal |
create and update also take applies_to= ("F-3 and not F-5"; "" clears it) and effectivity= ({"serials": "1-20, 25"}; {} clears it), and every change takes configuration= to propose it as an edit in that configuration (Product lines).
Errors
Every refused request raises holarch_api.ApiError with message (the server's text), code, status and body. The codes are those of the REST API. A request refused with 429 rate-limited is retried after the time the server names, up to retries times, before it raises.
Limits
- The API's limits apply (API and MCP): request rate, at most 500 entities per page, and the project's item limit when a proposal is applied.
- A proposal expires 7 days after it was started.
- The client works with the hosted service.