Sharing & links

systemHUB documents can be reached two ways, and an agent should know which one it’s handing out. They behave very differently.

The two link types

App links

A regular link to a document inside the app. Opening it requires the person to log in and have access (via role or direct assignment — see Roles & seats). If they can’t see the document in systemHUB, the link won’t show it to them.

An agent can construct an app link from the workspace alias and the document UUID (which every tree, search, and details response carries):

https://{alias}.systemhub.com/systems/{uuid}     ← Systems
https://{alias}.systemhub.com/policies/{uuid}    ← Policies
https://{alias}.systemhub.com/trainings/{uuid}   ← Trainings

This also works in reverse: when a user pastes an app URL at you, the UUID in it is the same UUID the MCP tools address — extract it and call get_system_details (or the matching section’s tool) directly. Caveats: this form requires login and access to the document, and the app won’t error on a malformed UUID until after login — so treat a constructed link as “the right address,” not proof the document exists.

Sending it to someone without a login? Add the share code to make it public — see the human-readable share link below. (Both forms were surfaced by SYSTEMologists in the field.)

Share links

A share link is a public URL for one document. Generate or retrieve one with:

→ get_document_share_link { "documentId": "7d4f2a90-…", "topicType": "system" }

Key behaviours:

• Designed for no-login access. The intent is that anyone holding the URL can fetch the published version as machine-readable JSON — the lightest-weight way to hand one process to an outside party or an AI without an MCP connection.
• It reuses an existing share code when the document already has one, and generates one if missing. Calling it twice doesn’t create two links.
• ⚠️ Share codes are not unique per document. Duplicating a document copies its share code, so the copy and the original share one code (reported and reproduced across two document pairs, 4 Aug 2026). If you’re building an index keyed on share codes, key on the document UUID instead — a share code can point at more than one document. Two code formats are also in circulation (longer codes on older documents, shorter on newer), so don’t validate them by shape.
• It shows the published version only — unpublished edits stay private until published (see Document lifecycle).
• Generating one requires SHARE permission on that document type.

⚠️ Known issue (verified 28 Jul 2026): fetching the raw api.systemhub.com/... share URL from outside returns 403 “Company not found” — that endpoint cannot resolve the workspace from the bare URL. Use the human-readable form below instead, which works.

The human-readable share link (use this one for people)

Take the share code from get_document_share_link and put it on the app host, qualified by your workspace alias:

https://{alias}.systemhub.com/systems/{uuid}/{shareCode}
https://{alias}.systemhub.com/policies/{uuid}/{shareCode}
https://{alias}.systemhub.com/trainings/{uuid}/{shareCode}

Verified 4 Aug 2026: this renders the published document in a browser with no login, in a clean session — title, Overview and Details. A wrong or missing share code returns 404, so the code is doing the work, not an existing session.

• {alias} is your company alias — your systemHUB subdomain, the part before .systemhub.com (the same value used as the OAuth Client ID; find it in Settings → AI Gateway).
• {uuid} is the document ID, present on every tree, search and details response.
• {shareCode} is the trailing path segment of the shareLink returned by the share-link tool (or the shareLink field on get_*_details).

Two behaviours worth knowing when you construct or inspect these links:

• The app rewrites to a guest route. Opening the link lands on /{section}/guest/{uuid}/{shareCode}?company={alias} — the alias carried explicitly. That’s expected; share the short form and let the app do the rewrite.
• The section segment is not validated. A system’s UUID and code requested under /policies/ still renders the system (reported 7 Aug 2026). So don’t infer a document’s section from the URL it was shared under — use discriminator on the document itself.

This is the link to give a human. It needs no login and no seat, which makes it the right answer for a contractor, an auditor, a client, or a team member on their phone.

⚠️ Agents: you cannot fetch this form. The share view is a client-rendered app, so a plain HTTP request (curl, an agent’s fetch tool, a link unfurler, a preview bot) gets the JavaScript shell — not the document. It only renders in a real browser. Two consequences: don’t try to read a document by fetching this URL (use get_*_details instead), and don’t treat a 200 as proof the link is valid — the 404 for a wrong share code is also rendered client-side, so status codes tell you nothing here.

There is currently no share URL an external agent can fetch without a browser. The api.systemhub.com form is the machine-readable one — it returns the published document as JSON — but it currently 403s externally (see the known issue above). Until that’s fixed, hand share links to people, and give programs MCP access instead.

get_*_details responses include a shareLink field (the URL, or null if none exists).

Rules for agents

• Never hide an existing share link. When presenting a document’s details, always surface its share link if one exists — it’s part of the document’s identity, not metadata to trim.
• Say which kind of link you’re giving. “Here’s the share link (public, no login)” vs “here’s the app link (they’ll need to log in)”. The difference matters to the user even when it doesn’t matter to you.
• Treat share links as public. Before generating one, make sure the user understands anyone with the URL can read the document. Don’t generate share links for sensitive documents unprompted.

Next: Errors & limits →