# Archyon

> REST API and developer docs for Archyon — the hosted architecture-mapping tool.

## Docs

- [Current org's Notion connection status](https://docs.archyon.app/api-reference/admin/current-orgs-notion-connection-status.md): Org admin sees the bound Notion workspace + the exact `redirectUri` they need to register in Notion (must match `PUBLIC_BASE_URL` char-for-char).
- [Disconnect Notion from this org](https://docs.archyon.app/api-reference/admin/disconnect-notion-from-this-org.md): Deletes the access token and workspace metadata from `org_integrations`. Existing component → Notion links remain but stop refreshing.
- [Get instance settings](https://docs.archyon.app/api-reference/admin/get-instance-settings.md): Currently empty — settings registry has no entries. Future settings will expose `{value, type, category, description}` with secret values masked as `"***configured***"`.
- [List all users on this instance](https://docs.archyon.app/api-reference/admin/list-all-users-on-this-instance.md)
- [List my (admin's) API tokens](https://docs.archyon.app/api-reference/admin/list-my-admins-api-tokens.md): Identical shape to `GET /api/me/tokens` — kept for the legacy admin UI.
- [Mint an admin API token](https://docs.archyon.app/api-reference/admin/mint-an-admin-api-token.md): Identical to `POST /api/me/tokens`. Bound to active org at mint time.
- [Recent audit events](https://docs.archyon.app/api-reference/admin/recent-audit-events.md)
- [Revoke an admin API token](https://docs.archyon.app/api-reference/admin/revoke-an-admin-api-token.md)
- [Test the Notion connection](https://docs.archyon.app/api-reference/admin/test-the-notion-connection.md): Calls `GET /v1/users/me` against Notion using the stored token. Useful for the admin to verify the integration is still alive and to surface bot/workspace names.
- [Update a user's admin/suspend flags](https://docs.archyon.app/api-reference/admin/update-a-users-adminsuspend-flags.md)
- [Update instance settings](https://docs.archyon.app/api-reference/admin/update-instance-settings.md)
- [Begin Notion OAuth](https://docs.archyon.app/api-reference/auth/begin-notion-oauth.md): Generates a Notion authorize URL bound to the current `(user, organization)` via a state nonce. Frontend redirects the browser to the returned `url`.
- [Notion OAuth callback](https://docs.archyon.app/api-reference/auth/notion-oauth-callback.md): Notion redirects the browser here after the user approves the connection. We exchange the code for an access token, persist it in `org_integrations` for the bound org, then 302 back to `/?notion=<status>` so the client can react.
- [Whoami](https://docs.archyon.app/api-reference/auth/whoami.md): Returns the authenticated user's basic profile. Used by the client's `AuthGate` to decide what to render once Clerk has a session.
- [Add a component](https://docs.archyon.app/api-reference/components/add-a-component.md)
- [Delete a component](https://docs.archyon.app/api-reference/components/delete-a-component.md): CASCADEs to its relationships, links, and stakeholder rows.
- [Update a component](https://docs.archyon.app/api-reference/components/update-a-component.md): When the body contains only `x` + `y`, takes a fast coords-only path (canvas drag).
- [Add an external link](https://docs.archyon.app/api-reference/links/add-an-external-link.md): If the URL matches `notion.so/…` and `kind` is not `"url"`, Archyon resolves the page via Notion's API to fill in `title`, `icon`, and `targetId`. Plain URLs are stored as-is.
- [List a component's external links](https://docs.archyon.app/api-reference/links/list-a-components-external-links.md): `notionConfigured` reflects the workspace's org, not the caller's.
- [Re-fetch a Notion-backed link's metadata](https://docs.archyon.app/api-reference/links/re-fetch-a-notion-backed-links-metadata.md): For plain `kind: "url"` links, returns `{link, unchanged: true}` without touching Notion.
- [Remove a link](https://docs.archyon.app/api-reference/links/remove-a-link.md)
- [Dynamic Client Registration (RFC 7591)](https://docs.archyon.app/api-reference/mcp/dynamic-client-registration-rfc-7591.md): Claude registers itself here on first connect. The response carries the `client_id` to use on the subsequent `/oauth/authorize` call. Public clients (every Claude installation today) don't receive a `client_secret`; PKCE replaces it.
- [OAuth 2.0 Authorization Server Metadata (RFC 8414)](https://docs.archyon.app/api-reference/mcp/oauth-20-authorization-server-metadata-rfc-8414.md): Discovery document Claude fetches to locate the OAuth endpoints (authorize, token, register, revoke).
- [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://docs.archyon.app/api-reference/mcp/oauth-20-protected-resource-metadata-rfc-9728.md): Discovery document Claude (and other MCP clients) fetch after receiving a `401` from `/mcp` with a `WWW-Authenticate` header pointing here. Tells the client which authorization server to use and what scopes are available.
- [Current user](https://docs.archyon.app/api-reference/me/current-user.md)
- [List my API tokens](https://docs.archyon.app/api-reference/me/list-my-api-tokens.md)
- [Mint a new API token](https://docs.archyon.app/api-reference/me/mint-a-new-api-token.md): The plaintext `token` is returned **once** and never again. Bound to the caller's active organization at mint time — tokens with no `orgId` (minted before JOH-109) only see instance-wide endpoints.
- [Revoke an API token](https://docs.archyon.app/api-reference/me/revoke-an-api-token.md): Soft-revoke (sets `revoked_at`). Owned-by-someone-else returns 404, not 403, to avoid leaking token existence.
- [Workspaces I am a member of](https://docs.archyon.app/api-reference/me/workspaces-i-am-a-member-of.md)
- [Add a workspace member](https://docs.archyon.app/api-reference/members/add-a-workspace-member.md)
- [Change a member's role](https://docs.archyon.app/api-reference/members/change-a-members-role.md)
- [List workspace members](https://docs.archyon.app/api-reference/members/list-workspace-members.md)
- [Remove a member](https://docs.archyon.app/api-reference/members/remove-a-member.md)
- [List the children of a Notion page or database](https://docs.archyon.app/api-reference/notion/list-the-children-of-a-notion-page-or-database.md)
- [Search the connected Notion workspace](https://docs.archyon.app/api-reference/notion/search-the-connected-notion-workspace.md): Thin proxy over Notion's `POST /v1/search`. Org must have Notion connected.
- [Create a person](https://docs.archyon.app/api-reference/people/create-a-person.md)
- [Delete a person](https://docs.archyon.app/api-reference/people/delete-a-person.md)
- [Get a person + their team memberships](https://docs.archyon.app/api-reference/people/get-a-person-+-their-team-memberships.md)
- [List people in the active org](https://docs.archyon.app/api-reference/people/list-people-in-the-active-org.md): Scoped to the caller's active organization. Returns `[]` when the session has no org context.
- [Update a person](https://docs.archyon.app/api-reference/people/update-a-person.md): Empty strings for `email` / `photoUrl` / `title` / `clerkUserId` are interpreted as `null`. `orgId` is immutable.
- [Create a process](https://docs.archyon.app/api-reference/processes/create-a-process.md): Processes are Mermaid `sequenceDiagram` flows whose `participant` aliases map to component ids via `participants`. The Architecture canvas resolves each step against the workspace's relationships and animates an electron along the edge.
- [Delete a process](https://docs.archyon.app/api-reference/processes/delete-a-process.md)
- [Get a process](https://docs.archyon.app/api-reference/processes/get-a-process.md)
- [List processes in a workspace](https://docs.archyon.app/api-reference/processes/list-processes-in-a-workspace.md)
- [Update a process](https://docs.archyon.app/api-reference/processes/update-a-process.md)
- [Add a relationship](https://docs.archyon.app/api-reference/relationships/add-a-relationship.md)
- [Delete a relationship](https://docs.archyon.app/api-reference/relationships/delete-a-relationship.md)
- [Update a relationship](https://docs.archyon.app/api-reference/relationships/update-a-relationship.md)
- [Create a custom role](https://docs.archyon.app/api-reference/roles/create-a-custom-role.md)
- [Delete a custom role](https://docs.archyon.app/api-reference/roles/delete-a-custom-role.md): Refuses to delete if any stakeholder link still uses the role — caller must reassign or remove them first.
- [List stakeholder link types (roles)](https://docs.archyon.app/api-reference/roles/list-stakeholder-link-types-roles.md): On first read for an org with zero rows, lazy-seeds the canonical defaults (owner, support, business-owner).
- [Update a custom role](https://docs.archyon.app/api-reference/roles/update-a-custom-role.md): Empty strings for `icon` / `iconName` are interpreted as `null`.
- [Built-in type catalogue](https://docs.archyon.app/api-reference/schema/built-in-type-catalogue.md): Returns the immutable type catalogue used to populate dropdowns.
- [Attach a person or team to a component](https://docs.archyon.app/api-reference/stakeholders/attach-a-person-or-team-to-a-component.md): Exactly one of `personId` / `teamId` must be set. Both refer to org-scoped entities in the workspace's org.
- [Detach a stakeholder](https://docs.archyon.app/api-reference/stakeholders/detach-a-stakeholder.md)
- [List stakeholders attached to a component](https://docs.archyon.app/api-reference/stakeholders/list-stakeholders-attached-to-a-component.md)
- [Add a member](https://docs.archyon.app/api-reference/teams/add-a-member.md)
- [Change a member's role](https://docs.archyon.app/api-reference/teams/change-a-members-role.md)
- [Create a team](https://docs.archyon.app/api-reference/teams/create-a-team.md)
- [Delete a team](https://docs.archyon.app/api-reference/teams/delete-a-team.md): CASCADEs to team_members. Child teams (if any) become root teams.
- [Get a team + its members](https://docs.archyon.app/api-reference/teams/get-a-team-+-its-members.md)
- [List a team's members](https://docs.archyon.app/api-reference/teams/list-a-teams-members.md)
- [List teams in the active org](https://docs.archyon.app/api-reference/teams/list-teams-in-the-active-org.md)
- [Remove a member](https://docs.archyon.app/api-reference/teams/remove-a-member.md)
- [Update a team](https://docs.archyon.app/api-reference/teams/update-a-team.md)
- [Submit a waitlist entry](https://docs.archyon.app/api-reference/waitlist/submit-a-waitlist-entry.md): Public endpoint used by the marketing site (`discover.archyon.app`). Returns the same `{ ok: true }` response whether the email is new or duplicate — does not reveal account existence.
- [Bulk replace workspace contents](https://docs.archyon.app/api-reference/workspaces/bulk-replace-workspace-contents.md): Atomic-ish "replace everything" call. Creates the workspace if missing (caller becomes owner). Replaces ALL components and relationships with the supplied arrays.
- [Create a workspace](https://docs.archyon.app/api-reference/workspaces/create-a-workspace.md): Caller becomes `owner`. Requires an active org (the workspace is bound to it permanently).
- [Delete a workspace](https://docs.archyon.app/api-reference/workspaces/delete-a-workspace.md): Owner role required. CASCADEs to components, relationships, stakeholders, processes, members.
- [Get a workspace with all nested content](https://docs.archyon.app/api-reference/workspaces/get-a-workspace-with-all-nested-content.md): Single bundled response: workspace metadata + every component, relationship, stakeholder link, and process. This is what the web app hydrates on workspace load.
- [List workspaces I can read](https://docs.archyon.app/api-reference/workspaces/list-workspaces-i-can-read.md): Filters to workspaces the caller can read. When the session has an active org, results are restricted to that org's workspaces (instance superadmins see all).
- [Update workspace metadata](https://docs.archyon.app/api-reference/workspaces/update-workspace-metadata.md): Changing `visibility` requires `owner` role; other fields require `editor`. `orgId` is immutable.
- [Authentication](https://docs.archyon.app/authentication.md): Bearer credentials — Clerk session JWTs for browser clients, Archyon Personal Access Tokens for everything else.
- [Connectors](https://docs.archyon.app/connectors.md): Add Archyon to Claude as a hosted MCP Connector.
- [Conventions](https://docs.archyon.app/conventions.md): Identifier formats, request semantics, and other invariants that apply across the API.
- [Errors](https://docs.archyon.app/errors.md): Status codes, the standard error envelope, and a reference of every documented error code.
- [Introduction](https://docs.archyon.app/introduction.md): REST API for Archyon — a hosted architecture-mapping platform.
- [Quickstart](https://docs.archyon.app/quickstart.md): Mint a token, list workspaces, and add a component and relationship — in about five minutes.

## OpenAPI Specs

- [openapi](https://docs.archyon.app/openapi.yaml)