> ## 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. # Bulk replace workspace contents > Atomic-ish "replace everything" call. Creates the workspace if missing (caller becomes owner). Replaces ALL components and relationships with the supplied arrays. Used by Reset to sample data, Import, and the seeding scripts. ## OpenAPI ````yaml /openapi.yaml put /api/workspaces/{id}/bulk 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/{id}/bulk: parameters: - $ref: '#/components/parameters/WorkspaceId' put: tags: - Workspaces summary: Bulk replace workspace contents description: | Atomic-ish "replace everything" call. Creates the workspace if missing (caller becomes owner). Replaces ALL components and relationships with the supplied arrays. Used by Reset to sample data, Import, and the seeding scripts. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkspaceBulkReplace' responses: '200': description: Replaced. content: application/json: schema: $ref: '#/components/schemas/WorkspaceBundleNoProcesses' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' components: parameters: WorkspaceId: in: path name: id required: true schema: type: string description: Workspace id (slug-like; provided at create time). schemas: WorkspaceBulkReplace: type: object required: - workspace properties: workspace: type: object required: - id properties: id: type: string description: Must match the URL `:id`. name: type: string description: type: string visibility: type: string enum: - org - members - private properties: type: object additionalProperties: true components: type: array items: $ref: '#/components/schemas/ComponentCreate' relationships: type: array items: $ref: '#/components/schemas/RelationshipCreate' WorkspaceBundleNoProcesses: type: object required: - workspace - components - relationships properties: workspace: $ref: '#/components/schemas/Workspace' components: type: array items: $ref: '#/components/schemas/Component' relationships: type: array items: $ref: '#/components/schemas/Relationship' ComponentCreate: type: object required: - id - typeId properties: id: type: string typeId: type: string name: type: string description: type: string x: type: number default: 0 'y': type: number default: 0 properties: type: object additionalProperties: true RelationshipCreate: type: object required: - id - sourceId - targetId - typeId properties: id: type: string sourceId: type: string targetId: type: string typeId: type: string label: type: string properties: type: object additionalProperties: true 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. Component: type: object required: - id - workspaceId - typeId - name - x - 'y' - properties properties: id: type: string workspaceId: type: string typeId: type: string name: type: string description: type: string x: type: number 'y': type: number properties: type: object additionalProperties: true Relationship: type: object required: - id - workspaceId - sourceId - targetId - typeId - properties properties: id: type: string workspaceId: type: string sourceId: type: string targetId: type: string typeId: type: string label: type: string properties: type: object additionalProperties: true 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: BadRequest: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found (or not visible to caller). content: application/json: schema: $ref: '#/components/schemas/Error' 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. ````