> ## Documentation Index > Fetch the complete documentation index at: https://docs.archyon.app/llms.txt > Use this file to discover all available pages before exploring further. # List workspaces I can read > 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). ## OpenAPI ````yaml /openapi.yaml get /api/workspaces openapi: 3.1.0 info: title: Archyon API version: 0.1.0 summary: REST surface for Archyon — the hosted architecture-mapping tool. description: > Archyon's REST API powers both the web app and the MCP server. It is organised around a few core resource families: - **Workspaces** — the unit of architecture content. Components + relationships + processes + stakeholder links + per-workspace membership all live under `/api/workspaces/{id}`. - **People + Teams + Roles** — org-scoped human entities that get attached to components as stakeholders. Sibling routes to `/api/workspaces`. - **Me + Admin** — self-service (profile, API tokens) and instance-superadmin (user management, audit log). - **Notion** — OAuth connect flow + a thin search/children proxy used when linking components to Notion pages. - **Waitlist** — the only fully public endpoint; used by the marketing site. ### Authentication All non-public endpoints take a Bearer token via `Authorization: Bearer …`. Two token kinds are accepted: | Token | Where it comes from | Lifetime | |---|---|---| | Clerk session JWT | Browser — Clerk SDK mints it from the active session | Short (≤1h) | | Archyon PAT (`an_pat_…`) | User mints one at `/account` → Tokens. Bound to the active Clerk organization at mint time. | Until revoked | Tokens belong to a Clerk **organization**. Any endpoint that touches org-scoped data (`/api/people`, `/api/teams`, `/api/stakeholder-link-types`, org-scoped workspaces) returns HTTP 400 with `code: "no_active_org"` if the caller has no org context. Switch organization in the Clerk OrgSwitcher (browser) or mint a new token while the desired org is active (CLI / MCP). ### Errors Every error response is JSON: ```json { "error": "Human-readable message.", "code": "machine_readable_tag" } ``` `code` is set when callers are expected to branch (e.g. show the "Connect Notion" CTA on `notion_misconfigured`). Plain validation errors omit `code`. contact: name: Archyon support url: https://archyon.app license: name: Proprietary url: https://archyon.app servers: - url: https://archyon.app description: Production - url: http://localhost:3000 description: Local dev (npm run dev) security: - bearerAuth: [] tags: - name: Auth description: Session bootstrap + Notion OAuth. - name: Schema description: Built-in type catalogue (component types, relation types, lifecycles). - name: Me description: Self-service — profile, API tokens, workspaces. - name: Admin description: Instance superadmin only. - name: Workspaces description: Workspace CRUD + bulk replace. - name: Components description: Components inside a workspace. - name: Relationships description: Edges between components. - name: Links description: External links attached to components (Notion pages, URLs). - name: Members description: Per-workspace membership + role. - name: Stakeholders description: People/teams attached to components with a role (owner, support, …). - name: Processes description: Mermaid-stored sequence flows that overlay the workspace canvas. - name: People description: Org-scoped people. - name: Teams description: Org-scoped teams + membership. - name: Roles description: Custom stakeholder link types (org-scoped). - name: Notion description: Search + children proxy against the connected Notion workspace. - name: Waitlist description: Public; for the marketing site. - name: MCP description: > Hosted Model Context Protocol server. The discovery endpoints are documented here so OpenAPI consumers can find them; the `/mcp` endpoint itself speaks the MCP Streamable HTTP transport, not REST. See [docs.archyon.app/connectors](https://docs.archyon.app/connectors). paths: /api/workspaces: get: tags: - Workspaces summary: List workspaces I can read description: | 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). responses: '200': description: OK. content: application/json: schema: type: object required: - workspaces properties: workspaces: type: array items: $ref: '#/components/schemas/WorkspaceSummary' '401': $ref: '#/components/responses/Unauthorized' components: schemas: WorkspaceSummary: allOf: - $ref: '#/components/schemas/Workspace' - type: object required: - componentCount - relationshipCount properties: componentCount: type: integer relationshipCount: type: integer Workspace: type: object required: - id - name - ownerUserId - visibility - properties - createdAt - updatedAt properties: id: type: string name: type: string description: type: string ownerUserId: type: integer orgId: type: - string - 'null' description: Clerk org id. Immutable after creation. visibility: type: string enum: - org - members - private properties: type: object additionalProperties: true createdAt: type: integer updatedAt: type: integer myRole: type: - string - 'null' enum: - owner - editor - viewer - null description: >- Caller's role on this workspace. Only populated by endpoints that gate on role. Error: type: object required: - error properties: error: type: string description: Human-readable error message. code: type: string description: | Machine-readable tag for callers that need to branch (e.g. `no_active_org`, `notion_misconfigured`, `role_in_use`). Omitted for plain validation errors. responses: Unauthorized: description: Missing or invalid Bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Not authenticated securitySchemes: bearerAuth: type: http scheme: bearer description: | Both Clerk session JWTs (browser) and Archyon Personal Access Tokens (`an_pat_…`, server / CLI / MCP) use the same Bearer header. The server distinguishes them by token shape. - **Clerk JWTs** carry org context in the token claims (`org_id`, `org_role`, `org_slug`) — required for org-scoped endpoints. Configure your Clerk session template to include these claims; see DEPLOYMENT.md. - **PATs** are minted at `/account` → Tokens. Each PAT is bound to whichever org was active at mint time. Switch orgs and re-mint to address a different org. ````