# Canopy - Full documentation > Every Canopy docs page, concatenated for LLMs and agents. Canonical pages live under https://canopy.8starlabs.com/docs. Short index: https://canopy.8starlabs.com/llms.txt --- # Source: https://canopy.8starlabs.com/docs import { ExportFlip } from "@/components/landing/viz/export-flip"; export const metadata = { title: "Introduction | Canopy Docs", description: "Learn how Canopy maps software systems and operational workflows, imports repositories, tracks cost, and exports context for AI agents.", alternates: { canonical: "/docs" }, }; # Introduction Canopy is a visual operational architecture workspace. **Draw a system before you build it**, or point it at a repo to **map a stack you've shipped** - then **operate** it with cost, metadata, and AI exports. Your nodes, edges, and cost stay first-class, machine-readable data: one map is at once an interactive canvas, a cost rollup, Markdown in sync, and your agents can read. A "system" isn't only a tech stack - map any **operational workflow** too: a marketing pipeline (HubSpot → Zapier → Mailchimp → GA4), RevOps, or internal automation. The library covers CRM, marketing, and automation tools, and maps tag as **Marketing** or **Operations**. ## The ideal flow ## Who is Canopy for If you can describe how the pieces connect - a tech stack or an operational workflow - Canopy keeps it as living, structured data you own. ## What makes Canopy different - **Guided input, not a blank canvas.** Import a GitHub repo or pick from 200+ tools, AI platforms, and workflows. - **Operational by default.** Owner, SLA, status, and cost live on every node. - **AI-native.** Export `CLAUDE.md` / `AGENTS.md` and expose your map over MCP. - **Always in sync.** `canopy.json` ⇄ canvas - describe a system and Canopy renders it both ways. - **Structured & yours.** Every map is data you own - exportable and portable. ## Where to next --- # Source: https://canopy.8starlabs.com/docs/accounts export const metadata = { title: "Accounts & workspaces | Canopy Docs", description: "Understand Canopy accounts, workspaces, roles, members, maps, and the permissions that control access to your systems.", alternates: { canonical: "/docs/accounts" }, }; # Accounts & workspaces Canopy is built around two layers: an **account** (you) and a **workspace** (your team and its maps). Everything useful - [maps](/docs/maps), members, roles, and billing - lives inside a workspace. ## Accounts An account is you. You sign in once - via **GitHub** or **email and password** - and your account follows you across every workspace you belong to. One email address, one account. Your account holds your personal profile, your [Canopy Card](/docs/canopy-card), and settings like your display name, handle, and avatar. That public identity is used on marketplace author cards and account previews. Deleting your account removes your personal data across all workspaces. You can add **two-factor authentication** - a 6-digit code from an authenticator app, required at every sign-in including GitHub ones. It comes with 10 single-use recovery codes in case you lose your phone. See [Two-factor authentication](/docs/security/two-factor). ## Workspaces A workspace is the **team and billing boundary**. [Maps](/docs/maps), members, [roles](/docs/team-billing), and subscriptions all live inside a single workspace. - Every workspace has exactly one **Owner**, who controls billing and invitations. - Every invited member - regardless of [role](/docs/team-billing) - occupies a **paid seat** on the workspace's Pro [subscription](/docs/team-billing/subscriptions). - Each workspace has its own **subscription**, separate from any other workspace you own or belong to. - Each workspace gets a unique **handle** (e.g. `/w/acme-corp`), which becomes its public profile URL if you choose to publish maps. Marketplace workspace previews use this workspace identity, separate from your account preview. ## Field rules The same limits apply in the app and on the server, so what you type is what gets saved: | Field | Requirement | | ---------------------------------- | ------------------------------------------------------------------------------- | | Display name | 2 to 50 characters | | Handle (account **and** workspace) | 3 to 30 characters; lowercase letters, numbers and hyphens only; must be unique | | Password | 8 to 72 characters | | Workspace name | 2 to 40 characters | | Role title | up to 60 characters | | Email | up to 120 characters | Most text fields let you keep typing past the limit but flag it inline and block saving until it is back in range. Handles are lowercased automatically, and passwords are hard-capped at 72 characters (the authentication limit). ## How they fit together ``` Account (you) └─ owns → Workspace (team + billing) ├─ Members (each a paid seat) └─ Maps └─ Nodes + Edges ``` One person can own multiple workspaces (each billed separately) and be a member of workspaces owned by others - with a different [role](/docs/team-billing) in each. ## Free workspaces Every account can own **up to two free workspaces**. To create more, upgrade one to Pro first - that frees a slot. Paid workspaces (Pro) are unlimited. See [Subscriptions & seats](/docs/team-billing/subscriptions) for plan limits. A workspace downgraded from Pro to Free is never deleted. If a downgrade would put you over the two-free-workspace cap, the surplus one goes **read-only** until you re-upgrade one, delete one, or free a slot. Your two oldest free workspaces stay editable; newer surplus ones become read-only (you can still read them, and re-upgrading or deleting a free workspace unlocks the rest). ## Workspace verification Pro workspace owners can apply for a **verified badge** (the blue seal) to show buyers that their public maps and templates come from a trusted source. Apply from **Workspace settings → Verification**. See [Trust & verification](/docs/marketplace/trust) for the full requirements. ## Roles are per workspace The same person can be an Owner in one workspace and a Viewer in another. Roles and seat costs are always scoped to a single workspace. See [Roles & permissions](/docs/team-billing) for what each role can do. ## Dormant accounts Inactive **free** accounts move through a notice-first lifecycle before any data is removed. Signing in resets the clock at any stage, and **accounts on an active paid plan are never treated as dormant**. - **3 months inactive** → a **warning email** with ~30 days to sign back in. - **+30 days** with no sign-in → **suspended**: your login is disabled and all workspaces you own become inaccessible, but **nothing is deleted**. The data is preserved. - **+30 days** still suspended → **permanently deleted** (a final-warning email goes out ~7 days before). Maps other people have **purchased are kept** (archived) so buyers aren't affected. Reactivate a suspended account anytime before deletion through **chat support** (the chat bubble on any page, available even when you're signed out); we'll confirm the account with you in the conversation. If your paid plan lapses to Free, the dormancy clock starts from the **downgrade date**, not your last sign-in. Full details, including marketplace and Stripe specifics, are in the [Dormant Account Policy](/dormant-account-policy). --- # Source: https://canopy.8starlabs.com/docs/api export const metadata = { title: "API & MCP | Canopy Docs", description: "Connect coding agents and applications to Canopy with the REST API, MCP server, workspace tokens, and map operations.", alternates: { canonical: "/docs/api" }, }; # API Canopy's **REST API** lets you read and write your [maps](/docs/maps) programmatically - a map is plain JSON you own. Prefer to let coding agents query your architecture instead? That's the [MCP server](/docs/mcp), a sibling of this API that shares the same token and rate limit. The REST API and MCP server require Pro - token creation is only available on paid workspaces. Building and exporting maps in the app stays free; only programmatic access needs a paid workspace. [See plans](/pricing). ## What's here - **[Authentication](/docs/api/authentication)** - create and use a workspace token. - **[Maps API](/docs/api/maps)** - list, get, create, update, delete, and export maps. - **[Rate limits & errors](/docs/api/rate-limits)** - quotas, headers, and the error catalog. The JSON you read and write follows the [map syntax](/docs/maps/architecture-as-code) - that reference lists every node and edge field and its accepted values. ## x402 & MPP Agent-native payments. **x402** and **MPP** (machine protocol payments) let an agent pay for a template or metered API access on its own, over the API, with no human in the loop. This is a heads-up, not a shipped capability. x402 & MPP are on the roadmap as a Pro feature - the badges above mark it as coming soon. --- # Source: https://canopy.8starlabs.com/docs/api/authentication export const metadata = { title: "Authentication | Canopy Docs", description: "Authenticate Canopy REST API and MCP requests with a workspace token and control which workspace an agent can access.", alternates: { canonical: "/docs/api/authentication" }, }; # Authentication The REST API authenticates with a **workspace token** sent as a bearer header. (The [MCP server](/docs/mcp) uses the same token, and additionally supports [OAuth](/docs/mcp/oauth) for agent clients.) ## Workspace tokens A workspace API token is a long-lived secret you create yourself. It's scoped to a single workspace and carries that workspace's permissions - treat it like a password. Send it as a bearer header on every request: The same token works for the MCP server - see [Connect with a token](/docs/mcp/token). ## Create a token Only the **workspace owner** can create, view, or revoke API tokens - Admins, Editors, and Viewers can't. Create one in **Settings → Workspace → [API tokens](/dashboard/settings/workspace/api)**: Go to **Dashboard → Settings → Workspace → API tokens**. Tokens belong to the workspace you have open, so switch workspaces first if you need a different one. Give it a name (e.g. `CI pipeline`), pick an **expiry** (never, or 30–365 days), and click **Create**. The secret - `cnpy_live_…` - is shown **once**; copy it immediately, since only a SHA‑256 hash is stored. Send it as a bearer token (above), stored in an env var like `CANOPY_TOKEN` - never commit it to source control. Anyone holding a token can read and write that workspace's maps. If one leaks, revoke it right away and create a replacement. A workspace can hold up to **10 active tokens** at once - revoke one to free a slot. ## Revoke a token Open **Settings → Workspace → [API](/dashboard/settings/workspace/api)**, find the token, and click **Revoke**. It stops working **immediately and everywhere** - the next request from the REST API **or** any [MCP](/docs/mcp/token) client using it returns `401 invalid_token`. To **rotate**, create a new token, update your client, then revoke the old one. For browser-based sign-in instead of a pasted token, see [OAuth for MCP clients](/docs/mcp/oauth) (read-only). --- # Source: https://canopy.8starlabs.com/docs/api/maps export const metadata = { title: "Maps API | Canopy Docs", description: "Read and write Canopy maps programmatically with the Maps API, including nodes, edges, metadata, and exportable JSON.", alternates: { canonical: "/docs/api/maps" }, }; # Maps API The REST endpoints for reading and writing [maps](/docs/maps). Every call needs a [workspace token](/docs/api/authentication); responses are JSON unless noted. Base URL: `https://canopy.8starlabs.com/api/v1`. ## List maps List every map in the workspace. **Responses** | Status | Meaning | | ----------------------- | --------------------------------------------------------------- | | `200 OK` | An array of maps in `maps`. | | `401 Unauthorized` | Missing or invalid token. | | `429 Too Many Requests` | Rate limit exceeded - see [Rate limits](/docs/api/rate-limits). | ## Get a map Fetch a single map with its nodes and edges. **Responses** | Status | Meaning | | ----------------------- | -------------------------------------- | | `200 OK` | The map, under `map`. | | `401 Unauthorized` | Missing or invalid token. | | `404 Not Found` | No map with that id in your workspace. | | `429 Too Many Requests` | Rate limit exceeded. | ## Create a map Create a new map. The body is the architecture JSON. **Responses** | Status | Meaning | | ----------------------- | ---------------------------------------------------- | | `201 Created` | The new map, under `map`. | | `400 Bad Request` | Invalid payload (e.g. missing `name`); see `fields`. | | `401 Unauthorized` | Missing or invalid token. | | `403 Forbidden` | Map exceeds your plan's node limit. | | `429 Too Many Requests` | Rate limit exceeded. | ## Update a map Update a map's name, nodes, edges, or metadata. Only the fields you send change. **Responses** | Status | Meaning | | ----------------------- | -------------------------------------- | | `200 OK` | The updated map, under `map`. | | `400 Bad Request` | Empty or invalid payload. | | `401 Unauthorized` | Missing or invalid token. | | `404 Not Found` | No map with that id in your workspace. | | `429 Too Many Requests` | Rate limit exceeded. | ## Delete a map Permanently delete a map. **Responses** | Status | Meaning | | ----------------------- | -------------------------------------- | | `200 OK` | The map was deleted. | | `401 Unauthorized` | Missing or invalid token. | | `404 Not Found` | No map with that id in your workspace. | | `429 Too Many Requests` | Rate limit exceeded. | ## Export a map Export a map as `png`, `markdown`, `claude`, `agents`, `figma`, or `notion`. **Responses** The body is the exported artifact itself - `text/markdown` for `markdown` / `claude` / `agents`, `application/json` for `figma` / `notion`, `image/png` for `png` - not a JSON envelope. | Status | Meaning | | ----------------------- | ---------------------------------------------------- | | `200 OK` | The exported file, in the format's content type. | | `400 Bad Request` | Unknown `:format`. | | `401 Unauthorized` | Missing or invalid token. | | `403 Forbidden` | Format is gated behind Pro (e.g. `figma`, `notion`). | | `404 Not Found` | No map with that id in your workspace. | | `429 Too Many Requests` | Rate limit exceeded. | Architecture map exported from Canopy.\n\n## Services\n\n- **API** - node · trpc ($2.1k)\n\n## Dependencies\n\n- web → api`, }, { label: "400 Bad Request", lang: "json", code: `{\n "error": "invalid_request",\n "message": "Unknown export format \\"pdf\\". Supported: png, markdown, claude, agents, figma, notion."\n}`, }, { label: "401 Unauthorized", lang: "json", code: `{\n "error": "invalid_token",\n "message": "The API token is invalid, expired, or revoked."\n}`, }, { label: "403 Forbidden", lang: "json", code: `{\n "error": "forbidden",\n "message": "The \\"figma\\" export requires a Pro plan."\n}`, }, { label: "404 Not Found", lang: "json", code: `{\n "error": "not_found",\n "message": "Map not found."\n}`, }, { label: "429 Too Many Requests", lang: "json", code: `{\n "error": "rate_limited",\n "message": "Rate limit exceeded. Retry after 41s.",\n "retryAfter": 41\n}`, }, ]} /> ## The map object A `GET` returns a map wrapped in `{ "map": … }` (or `{ "maps": [ … ] }` for the list). The full object: | Field | Type | Notes | | ------------------------- | ------- | ---------------------------------------- | | `id` | string | Stable map id (the `:id` in URLs). | | `workspaceId` | string | The workspace the map belongs to. | | `name` | string | Map name. | | `isPublic` | boolean | Whether the map has a public share link. | | `nodes` | Node[] | The services - see below. | | `edges` | Edge[] | The connections - see below. | | `createdAt` / `updatedAt` | string | ISO‑8601 timestamps. | **Node** - `id` is always present; the rest appear only when set: | Field | Type | Notes | | ---------- | -------- | ------------------------------------------------------------------------------------------- | | `id` | string | Stable node key (edges reference it). | | `label` | string | Display name. | | `tech` | string | Sub-label, e.g. `"node · trpc"`. | | `spend` | number | Monthly cost as a plain number, e.g. `2100`. No currency symbol. | | `currency` | string | Optional ISO 4217 code (USD, EUR, GBP, JPY, CNY, CAD, AUD, CHF, INR, SGD). Defaults to USD. | | `billing` | string[] | Any of `seat`, `team`, `usage`, `flat`. | | `x`, `y` | number | Canvas position. | **Edge** - `source` and `target` are node `id`s; every other field is optional styling, matching the visual editor and `canopy.json` exactly (so an API round-trip preserves it): | Field | Type | Notes | | ------------ | ------- | ---------------------------------------------------------------------------------- | | `source` | string | Start node `id` (**required**). | | `target` | string | End node `id` (**required**). | | `line` | string | Curve style: `bezier` · `smoothstep` · `step` · `straight`. Defaults to `bezier`. | | `label` | string | Text at the edge midpoint (max 120 chars). Handy for workflow handoffs/conditions. | | `labelColor` | string | Label text color: hex, `rgb()`/`hsl()`, or a named color. | | `labelSize` | number | Label font size in px, `6`-`48` (default `10`). | | `labelFont` | string | Label typeface: `sketch` (Excalifont, default) · `sans` · `mono`. | | `arrow` | string | Arrowheads / direction: `none` · `end` (single) · `both` (bidirectional). | | `color` | string | Stroke color: hex, `rgb()`/`hsl()`, or a named CSS color. Overrides the gradient. | | `dotColor` | string | Moving-dot color; defaults to the edge `color`. | | `animated` | boolean | The moving flow dot. Defaults to `true`; `false` for a static line. | | `dashed` | boolean | Dashed stroke. Defaults to `false`. | Unsafe colors (anything that isn't a hex / `rgb()` / `hsl()` / named color) are rejected with `400`. ```json { "map": { "id": "acme-platform", "workspaceId": "ws_8s7d6f5g", "name": "8StarLabs Platform", "isPublic": false, "nodes": [ { "id": "web", "label": "Web", "tech": "next.js", "spend": 1200, "x": 0, "y": 96 }, { "id": "api", "label": "API", "tech": "node · trpc", "spend": 2100, "billing": ["flat"], "x": 240, "y": 120 } ], "edges": [{ "source": "web", "target": "api", "line": "bezier" }], "createdAt": "2026-05-01T10:00:00.000Z", "updatedAt": "2026-06-01T12:30:00.000Z" } } ``` ### Request body When you **create** or **update** a map you send only the editable fields - `name`, `nodes`, `edges`, and optional `isPublic`. The server assigns `id`, `workspaceId`, and the timestamps. ```json { "name": "8StarLabs Platform", "nodes": [{ "id": "web", "label": "Web", "tech": "next.js" }], "edges": [{ "source": "web", "target": "api" }] } ``` --- # Source: https://canopy.8starlabs.com/docs/api/rate-limits export const metadata = { title: "Rate limits & errors | Canopy Docs", description: "Understand Canopy API and MCP rate limits, error responses, retry behavior, and practical ways to handle failed requests.", alternates: { canonical: "/docs/api/rate-limits" }, }; # Rate limits & errors ## Rate limits The API is a **Pro feature**. Requests are rate limited **per workspace** (all of a workspace's tokens share one quota - minting more doesn't raise it), and [MCP](/docs/mcp) tool calls count against the **same** quota: | Window | Limit | | ------------------------------ | ------------ | | Reads (GET) | 600 / min | | Writes (POST · PATCH · DELETE) | 60 / min | | Burst (read + write) | 30 / sec | | Daily total | 10,000 / day | **Writes are held about ten times tighter than reads.** A write is the expensive side: updating a map replaces its whole node and edge set, so one call rewrites many rows. It is also the destructive side. Nothing legitimate needs write volume - importing a repo is a single create, an editing session is a handful - so the ceiling is set well above real use and well below what a looping client can burn through. This mirrors how [GitHub](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api) caps content-generating requests far below its general budget. [MCP](/docs/mcp) tools draw from the same two buckets: the read tools count as reads, and `create_map` / `update_map` / `delete_map` count as **writes**. The same operation costs the same whether it arrives over REST or MCP. The per-minute and burst limits cap how _fast_ you can call; the **daily total** caps overall volume and **resets daily at 00:00 UTC** - the same instant for every workspace. Hitting the daily cap returns `429` with `"Daily request quota exceeded."` and a `Retry-After` counting down to midnight UTC. Running into these ceilings at scale? [Talk to support](/support) and we'll raise them. Every response carries the current limit state in its headers, so you can back off before you're throttled: | Header | Example | Meaning | | --------------------- | ------- | -------------------------------------- | | `RateLimit-Limit` | `600` | Requests allowed in the current window | | `RateLimit-Remaining` | `588` | Requests left before you're throttled | | `RateLimit-Reset` | `41` | Seconds until the window resets | | `Retry-After` | `41` | Seconds to wait - only sent on a `429` | When you exceed the limit the API responds with `429 Too Many Requests` and a JSON body describing when to retry: Honor the `Retry-After` header with exponential backoff and jitter rather than retrying immediately - tight retry loops just burn your remaining budget. Batch writes where you can. You can watch today's usage (REST API vs MCP, split out) and the daily history in **Dashboard → Settings → Workspace → API**. [Embedded maps](/docs/maps/embed) are a public, cached, credential-free surface - they carry no token, so they never touch these quotas. A widely-embedded map costs you nothing against your API limits. ## Abuse protection & auto-disable A `429` is not a penalty - it just means "slow down." A well-behaved client that honors `Retry-After` is never punished. But a client that **keeps hammering through its own `429`s at a high sustained rate** (ignoring `Retry-After`) is treated as abuse, and the token is **automatically disabled**. - Detection is **rate-based**: it only trips on a sustained flood of requests sent _while already rate-limited_ (on the order of tens per second). Normal usage, and even an occasional retry after a limit, never trigger it. - A disabled token stops authenticating immediately (`401 invalid_token`), exactly like a revoked one. - **There is no re-enable.** The token shows as **Disabled** in **Settings → Workspace → API** with the reason; the fix is to **delete it and create a new one**. (Rotating is also the right move if a token has leaked - the disable usually means someone is misusing it.) Honor the `Retry-After` header with exponential backoff and jitter. Tight retry loops don't just burn your budget - sustained ones will get the token disabled. ## Log retention Each request (REST and MCP) is recorded to a per-workspace activity log, surfaced as **Recent requests** on the API page: what ran (the endpoint, or the MCP tool name), which map it touched, who authorized it, the status, and how long it took. Logs are **retained for 30 days, then automatically deleted**, and can be filtered and exported as CSV. The log is for observability only; it's never used for billing. Two things it deliberately doesn't capture: **rejected sign-ins** (a `401` never reaches the log) and requests **turned away during a burst** (those are refused before any database work, which is what keeps a flood cheap). Logging is also best-effort, so a database blip can drop a row. A quiet log is not proof that nothing happened - for abuse specifically, rely on the auto-disable behaviour above rather than on log volume. ## Errors Every error shares the same JSON envelope - a machine-readable `error` code, a human `message`, and sometimes extra fields (`fields`, `limit`, `retryAfter`). Always branch on the HTTP status and the `error` code, never on `message` text. | Status | `error` code | When | | ------ | ----------------- | ----------------------------------------------------------------------------------------------------------- | | `400` | `invalid_request` | Malformed body, missing required field, or unknown export format. | | `401` | `unauthorized` | No bearer token supplied. | | `401` | `invalid_token` | Token unknown, expired, or revoked. | | `403` | `node_limit` | Map exceeds your plan's node cap. | | `403` | `forbidden` | Feature gated behind a higher plan, or the credential is missing a required [scope](/docs/mcp#permissions). | | `404` | `not_found` | The map doesn't exist in your workspace. | | `429` | `rate_limited` | Too many requests - back off per `Retry-After`. | | `500` | `server_error` | Something failed on our side; safe to retry. | A `500` carries an `X-Request-Id` header - include it when you contact support so we can trace the failure. These are transient; retry with backoff. --- # Source: https://canopy.8starlabs.com/docs/canopy-card export const metadata = { title: "Canopy Card & badges | Canopy Docs", description: "Learn how Canopy Cards and badges represent your mapped systems, public profile, workspace identity, and product activity.", alternates: { canonical: "/docs/canopy-card" }, }; # Canopy Card & badges Every Canopy account has a shareable **Canopy Card** - a living trophy that reflects how much you've mapped. You earn a **badge** for each thing you do, and the **combination** of your badges unlocks your overall **title**. Find yours in **Account settings → Your Canopy Card**, and your public profile lives at **canopy.8starlabs.com/a/<your-handle>**. Click a title preset, toggle **Free / Pro workspace** to see the premium background, and hover the title ladder to preview each title on the card. ## Badges & tiers You earn three badges - one per "component" - and each rises through four **tiers**: Bronze, Silver, Gold, Platinum. Here's exactly how each looks, and the count needed to reach each tier: | Badge | Bronze | Silver | Gold | Platinum | | --------------- | ------ | ------ | ---- | -------- | | **Public maps** | 1 | 3 | 6 | 12 | | **Likes** | 3 | 10 | 25 | 60 | | **Clones** | 1 | 4 | 12 | 30 | - All three badges count **public maps only** - private maps never affect your card. The **Public maps** badge counts how many of your maps are currently public; **likes** and **clones** are summed across only those public maps. - The totals track your **current** public maps. Make a public map private and it (and its likes and clones) **immediately drops out** of the counts shown on your card and public profile - only your earned **title** is kept (see Titles below). - Every tier - including **Platinum** - is **free to earn**. Platinum wears a premium holographic finish. - Bronze/Silver/Gold/Platinum apply **only to the badges** - not to your title. ## Titles Your **title** is simple: to unlock the next one, **all three badges** must reach its tier. So you're only as high as your lowest badge - keep all three moving. Every title is **free to earn** - Pro only changes the card's looks. A title, once earned, is **kept forever** - deleting a map or losing likes never demotes you. Your title is per **workspace** (the card shows whichever workspace you pick). ## How to earn it Every map grows the **Maps** badge. Import a repo, clone a template, ask Canopy AI, or build by hand. Make a map public; likes on it grow the **Likes** badge. When someone clones one of your public maps, your **Clones** badge grows - a sign your architecture is worth copying. Your title only moves up when **all three badges** reach the next tier - so grow whichever badge is furthest behind. ## What the card shows - Your **title**, with its custom emblem icon (sprout → crown). - Your three **badges** (maps, likes, clones) as small metal icons. - The **workspace** you've chosen to display, with a **Pro** badge and a **Verified** seal when it qualifies. - A **scannable QR code** to your public profile, the date you joined, and a link to canopy.8starlabs.com. ## Pro card aesthetics A Pro workspace gives the card a premium finish - badges and titles stay free either way: - The card body picks up the signature **pastel mesh + dot grid** background. - Richer card art at the higher titles. - The **full set of card colors** unlocks as you climb. Free cards are clean and shareable too - Pro just makes them shine. See the [pricing page](/pricing) for the full comparison. ## Your public profile Your Canopy Card is displayed on **your public profile**. Set a unique **handle** in [Account settings](/dashboard/settings) to claim your page at **canopy.8starlabs.com/a/<handle>** - it shows your card and totals (maps, likes, clones) plus the workspaces you're on. The card's QR code links straight to it. A handle is **3 to 30 characters**, using lowercase letters, numbers and hyphens only, and must be unique. Your marketplace account preview uses the same public profile identity: display name, handle, selected avatar, Canopy Card title, and public map stats. Email addresses are not shown on public cards or marketplace previews. ## Sharing your card Use **Share on X**, **Copy PNG**, or **Download** beneath the card. The export is a crisp 2x PNG - perfect for a profile, a README, or a "now mapping" post. --- # Source: https://canopy.8starlabs.com/docs/glossary export const metadata = { title: "Glossary | Canopy Docs", description: "The vocabulary used across Canopy - maps, nodes, workspaces, seats, templates, licenses and more, each defined in plain language. Searchable.", alternates: { canonical: "/docs/glossary" }, }; # Glossary Learn the terms we use across Canopy and these docs. Each one maps to a real concept in the product, so you can read the rest of the documentation - and the app - without guessing what a word means. Filter by term or definition, and click any linked term to jump to its full page. ## The shape of it If you remember nothing else, remember the hierarchy - everything else hangs off it: > An **account** owns one or more **workspaces**. A workspace holds **maps**, and > each map is made of **nodes** and **edges**. The workspace is the team and > billing boundary: roles, **seats**, and the plan all live there. ## Next - [Accounts & workspaces](/docs/accounts) - how the layers fit together. - [Map syntax](/docs/maps/architecture-as-code) - the node and edge schema in full. - [Marketplace](/docs/marketplace) - templates, licenses, and selling. --- # Source: https://canopy.8starlabs.com/docs/maps export const metadata = { title: "Maps | Canopy Docs", description: "Learn how to build, import, edit, group, export, and share living Canopy maps for software systems and workflows.", alternates: { canonical: "/docs/maps" }, }; # Maps Everything about building a Canopy map - from capturing your stack to exporting it for AI and docs. Pick whichever starting point fits; they all land on the same editable canvas. ## Where to go next - [Import a repo](/docs/maps/import) - scan a GitHub repo and generate a first-draft map automatically. - [Clone a template](/docs/maps/templates) - start from a community map or curated template. - [Build by hand](/docs/maps/build) - drop nodes and draw edges on a blank canvas. - [Import from canopy.json](/docs/maps/import-json) - paste a map file and Canopy renders the architecture. - [Use your own AI](/docs/maps/use-your-own-ai) - let Claude, Codex or any MCP client build the map for you with `create_map`. - [Export formats](/docs/maps/exports) - Markdown, PNG, AI context, Figma, Notion, and JSON. - [Map syntax](/docs/maps/architecture-as-code) - the full JSON schema you edit, paste, or generate. --- # Source: https://canopy.8starlabs.com/docs/maps/architecture-as-code export const metadata = { title: "Map syntax (architecture as code) | Canopy Docs", description: "The full Canopy map syntax and JSON schema - node fields, edge fields, accepted values, and examples.", alternates: { canonical: "/docs/maps/architecture-as-code" }, }; # Map syntax Every Canopy map is plain **JSON** - easy to read, diff, and edit by hand or with an agent. This page is the complete **syntax / schema reference**: every field, its type, and its **accepted values**. (Canopy calls this "architecture as code".) Open any map and switch the editor to **Split** or **Code** to see it; edit the canvas or edit the JSON and they stay in sync. Plain JSON means your maps are portable - version them in git, generate them from a script, or read and write them through the [API](/docs/api) and [MCP server](/docs/mcp). The **Code** editor has autocomplete (IntelliSense). As you type, it suggests field names, **icon slugs** (type a tool or step - `stripe`, `next`, `approval` - and pick the mark), **billing models**, **edge line types**, and the **node ids** an edge can point to. Press `⌘` `.` (`Ctrl` `.` on Windows/Linux) to re-open suggestions, `↑` `↓` to move, `Enter` or `Tab` to accept. ## Shape A map is an object with two arrays, `nodes` and `edges` (an optional `name` is also stored): ```json { "name": "AI support workflow", "canvas": { "currency": "USD" }, "nodes": [ { "id": "inbox", "label": "Inbox", "brand": "intercom", "spend": 199 }, { "id": "agent", "label": "Triage agent", "brand": "openai", "spend": 840, "currency": "EUR" }, { "id": "review", "label": "Human review", "brand": "generic-approval", "spend": 0 } ], "edges": [ { "source": "inbox", "target": "agent" }, { "source": "agent", "target": "review" } ] } ``` Only `id` is required on a node; `source` and `target` are required on an edge. Every other field is optional. Canopy also stores a `canvas` object with your per-map view settings (`background`, `edgeStyle`, `minimap`, `snapToGrid`) plus the map's `currency`. The view settings are written automatically when you save and restored on load, so you don't need to author them by hand, and older files without them fall back to the defaults. `currency` is the one required `canvas` field: the map's base currency as an ISO 4217 code (one of USD, EUR, GBP, JPY, CNY, CAD, AUD, CHF, INR, SGD). It defaults to the workspace currency, and any node without its own `currency` override uses it. ## Node fields | Field | Type | Required | Accepted values | Notes | | --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | **yes** | Letters, digits, `-`, `_` only - `/^[A-Za-z0-9_-]+$/`. Unique within the map. | The node's stable key; edges reference it. | | `label` | string | – | Any text (kept ≤ 80 chars). | Display name on the canvas. Defaults to `id` when omitted. | | `tech` | string | – | Any text (kept ≤ 60 chars). | Tool, runtime, role, or step under the name, e.g. `"node · trpc"` or `"approval"`. Also accepted as `sub`. | | `brand` | string | – | An **icon slug** from the [Icon library](/docs/maps/icons), e.g. `"postgresql"`, `"openai"`. | Brand icon. Also accepted as `icon`. An unknown slug → a neutral box node. | | `purpose` | string | – | Any text (kept ≤ 160 chars). | What the service does; shown in the inspector and in `CLAUDE.md`/`AGENTS.md` exports. | | `spend` | number | – | A plain number, e.g. `840`. No symbol. | **Monthly** cost as a plain number in the map's currency. Always the monthly figure, even when entered at another interval. Defaults to `0`. | | `currency` | string | – | One of `"USD"`, `"EUR"`, `"GBP"`, `"JPY"`, `"CNY"`, `"CAD"`, `"AUD"`, `"CHF"`, `"INR"`, `"SGD"`. | Optional ISO 4217 code overriding the map's `canvas.currency` for this node's spend. | | `spendInterval` | string | – | One of `"day"`, `"week"`, `"month"`, `"year"`. Defaults to `"month"`. | The interval the cost was **entered** at. `spend` is still stored monthly; this just records how it was typed so the editor shows it back. | | `billing` | string[] | – | Any of `"seat"`, `"team"`, `"usage"`, `"flat"`. Unknown values are dropped. | Billing-model tags shown on the node and rolled up on the Intel page. | | `billingConfig` | object | – | Per-type inputs: `flat`/`usage` → `{ "amount": n }`; `seat`/`team` → `{ "price": n, "qty": n }`. | Optional raw cost breakdown per billing type (at `spendInterval`). The editor computes `spend` (monthly) from it. | | `x`, `y` | number | – | Any number (pixels). | Canvas position. **Auto-assigned** when omitted - see Auto-layout. | There is no per-node `color`. The map has a single accent colour set from the editor; individual nodes take their hue from their `brand` icon. ## Edge fields | Field | Type | Required | Accepted values | Notes | | ------------ | ------- | -------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `source` | string | **yes** | An existing node `id`. | The edge's start. (This is `source`, **not** `from`.) | | `target` | string | **yes** | An existing node `id`. | The edge's end. (This is `target`, **not** `to`.) | | `line` | string | – | One of `"bezier"`, `"smoothstep"`, `"step"`, `"straight"`. | Edge curve style. Defaults to `"bezier"`; an invalid value falls back to `"bezier"`. | | `label` | string | – | Any short string (max 120 chars). | Text drawn at the edge midpoint. Omit for no label. | | `labelColor` | string | – | A CSS color: hex, `rgb()`/`hsl()`, or a named color. | Label text color. Defaults to a muted foreground. | | `labelSize` | number | – | Integer `6`-`48`. | Label font size in px. Defaults to `10`. | | `labelFont` | string | – | One of `"sketch"`, `"sans"`, `"mono"`. | Label typeface. `"sketch"` (Excalifont) is the default; all are open-source (SIL OFL). | | `arrow` | string | – | One of `"none"`, `"end"`, `"both"`. | Arrowheads / direction. `"end"` = single arrow at the target, `"both"` = bidirectional. Defaults to `"none"`. | | `color` | string | – | A CSS color: hex (`"#38bdf8"`), `rgb()`/`hsl()`, or a named color. | Overrides the default gradient stroke. Invalid values are ignored. | | `dotColor` | string | – | A CSS color: hex, `rgb()`/`hsl()`, or a named color. | Color of the moving flow dot. Defaults to the edge `color` (or the gradient accent). | | `animated` | boolean | – | `true` or `false`. | The moving-dot flow animation. Defaults to `true`; set `false` for a static line. | | `dashed` | boolean | – | `true` or `false`. | Dashed stroke instead of solid. Defaults to `false`. | | `id` | string | – | Any string. | Optional stable edge id; auto-generated when omitted. | Both ends must reference a node `id` that exists in the same `nodes` array - edges with a missing or unknown `source`/`target` are silently dropped. ## Auto-layout When `x`/`y` are omitted on any node, Canopy assigns positions automatically using a **left-to-right layered layout**: each depth level from the edge graph gets its own column (spaced 240 px apart), and nodes in the same column are evenly distributed vertically (96 px row height). Once you drag a node, its position is written back to the JSON and no longer auto-managed. ## Minimal map Only `id` (nodes) and `source`/`target` (edges) are required: ```json { "nodes": [{ "id": "web" }, { "id": "api" }, { "id": "db" }], "edges": [ { "source": "web", "target": "api" }, { "source": "api", "target": "db" } ] } ``` ## Full example ```json { "name": "AI SaaS", "canvas": { "currency": "USD" }, "nodes": [ { "id": "web", "label": "Web App", "tech": "next.js", "brand": "nextdotjs", "purpose": "Frontend application", "spend": 1200, "billing": ["flat"], "x": 0, "y": 96 }, { "id": "api", "label": "API", "tech": "node · trpc", "brand": "nodedotjs", "purpose": "Backend REST API", "spend": 2100, "billing": ["flat"], "x": 240, "y": 144 }, { "id": "db", "label": "Postgres", "brand": "postgresql", "purpose": "Primary database", "spend": 840, "billing": ["usage", "team"], "x": 480, "y": 48 }, { "id": "llm", "label": "LLM", "brand": "openai", "purpose": "AI completions", "spend": 2800, "billing": ["usage"], "x": 240, "y": 240 } ], "edges": [ { "source": "web", "target": "api" }, { "source": "api", "target": "db", "line": "step" }, { "source": "api", "target": "llm" } ] } ``` ## Editing - **Add node** opens the [tool and icon library](/docs/maps/icons) - search every brand, workflow platform, AI tool, or pick a generic service or workflow box. - The **inspector** edits a node's label, tool/step sub-label, icon (`brand`), monthly cost, purpose, and billing tags. - **Drag between handles** to connect; drag a node to move it - its `x` / `y` are written back to the JSON. - A **map colour** swatch sets the map's accent, reflected on the dashboard overview. - If the JSON is invalid, the offending line is flagged and the canvas keeps your last valid render until you fix it. ## Importing Already have a map written to this syntax? You can paste it straight in via **New map → Paste canopy.json** - see [Import from canopy.json](/docs/maps/import-json) for the full flow and what gets validated. ## Next - [Icon library](/docs/maps/icons) - every `brand` slug, searchable. - [Nodes](/docs/maps/nodes) - the service inspector and metadata. - [Edges](/docs/maps/edges) - connections in depth. - [Exports](/docs/maps/exports) - JSON, Markdown, CLAUDE.md and more. --- # Source: https://canopy.8starlabs.com/docs/maps/blast-radius import { BlastRadiusDemo } from "@/components/docs/blast-radius-demo"; export const metadata = { title: "Blast Radius | Canopy Docs", description: "See what services are connected to a map node, how far away they are, and where to stop the impact review.", alternates: { canonical: "/docs/maps/blast-radius" }, }; # Blast Radius Blast Radius answers a practical question: **if I change this service, what else should I check?** It starts at the service you select, then follows the lines connected to it. The result is based on your map, not live traffic or production monitoring. Select a service. The orange highlight shows the connected services. Stronger color means closer to the selected service. Softer color means farther away. Gray lines are outside the current review. There is one color for the whole impact view. ## The rule: Blast Radius follows connected map topology Every line has a start and an end, stored as `source → target`. For example: ```text Web app → API → Payments ``` If **API** is selected: - Web app is **incoming**, also called **upstream**. - Payments is **outgoing**, also called **downstream**. - Blast Radius shows both sides in the same color. Incoming and outgoing are labels that help you read the arrows, not separate modes or colors. | Term | Meaning | | ------------------------- | --------------------------------------- | | **Focus** | The service you selected. | | **Direct** | A service one line away from the focus. | | **Transitive** | A service two or more lines away. | | **Incoming / upstream** | The line points into the focus. | | **Outgoing / downstream** | The line points away from the focus. | The meaning of an arrow depends on your map. In a request map, upstream is often a caller and downstream is often a dependency. In an event map, upstream may be the producer and downstream the consumer. The walk stops at the depth you choose, when there are no more connected lines, or at a boundary that you set. ## A concrete map In this example, the arrows describe request and data flow: ```text Browser → Web app ─┐ ├→ API gateway → Auth Mobile app ─────────┘ └→ Payments → Postgres └→ Queue ``` Select **API gateway** in the example below: - **Direct services:** Web app, Mobile app, Payments, and Auth. - **Transitive services:** Browser, Postgres, and Queue. - **Affected services:** every service reached within the selected depth. Use the controls in the example to change the depth or add a boundary. Click a different node to see its connected services. ## How to use Blast Radius 1. Open a map. Press `B`, choose **Blast radius** in the left toolbar, or press `⌘K` and search for **Toggle Blast Radius**. On Windows and Linux, use `Ctrl K`. 2. Click the service you are about to change. This becomes the **focus**. 3. Start with **All** to see the full connected map. Use **1 hop** or **2 hops** for a smaller review. 4. Follow the orange lines. Strong lines are close to the focus. Softer lines are farther away. 5. Open **Review services** to see a compact list of affected services and their hop count. Use **Block here** or **Allow past** on a row to control that branch. 6. Use **Block here** when the highlight should stop at a service. 7. Use **Fit impact** if part of the result is off screen. 8. Use **Pin focus** if you want to edit another node or line without changing the focus. Press `B`, click the left toolbar button, or choose **Toggle Blast Radius** from `⌘K` again to exit. Blast Radius is a temporary view. It does not save the focus, depth, color, boundaries, or pin state into the map. ## What the controls mean ### Color and distance Blast Radius uses one color for the whole review: - **Orange** is the default. - Direct connections use the strongest color. - Farther connections become softer, but stay visible. - Lines outside the result stay muted and are not part of the impact count. - Flow dots pause in Blast Radius so the impact path stays still while you review it. Use the color swatch or picker in the panel to choose another accent. The same color is used for the focus, nodes, and highlighted lines. The four node handles are only connection positions. They do not create four Blast Radius directions. ### Depth Depth is the number of lines Canopy may follow from the focus. It is not zoom: - **1 hop:** show only services directly connected to the focus. - **2 hops:** include one more layer. - **All:** continue until there are no more reachable services or a boundary. ### Boundaries Use **Block here** when the highlight should stop at a service. This is useful when the next system is outside the part of the map you are reviewing, such as: - another team's service; - a queue or webhook reviewed separately; - a shared platform service; - a database or vendor boundary. The boundary service stays highlighted. The lines after it stay visible in gray, but they are not counted or highlighted. Choose **Allow past** to remove the boundary. Use **Clear** to remove all boundaries. ### Pin focus Pinning keeps the current focus while you work on the map: - Clicking another **node** opens it in the editor without changing the focus. - Clicking a **line** still lets you change its style, label, arrows, or delete it. - **Review services** and **Fit impact** continue to work. Turn off **Pin focus** when you want to choose a new focus from the canvas. ## Important edge-direction details ### An invisible arrow still has a direction Even when an edge has no visible arrowhead, it still has a stored start and end. Blast Radius can follow it from either endpoint, but other readers cannot tell the intended direction. Add an arrowhead when direction matters. ### Two arrowheads do not create two edges Choosing **Both** draws arrowheads at both ends, but it still creates one edge. For a real two-way relationship, create two edges: ```text service-a → service-b service-b → service-a ``` This makes the relationship explicit in the map and in exports. ### Labels explain the relationship Use a label such as `REST`, `webhook`, `reads`, `publishes`, or `owns` to explain why a line exists. Labels do not change the result, but they make it easier to understand. ## Reading the result in a real change review Suppose you are changing **Payments** in the example: - Direct impact includes API gateway, Postgres, and Queue. - Transitive impact includes Web app, Mobile app, Browser, and Auth. - The full result includes every service reached within the selected depth. That gives you a practical review order: 1. Check direct neighbors first. They are closest to the change. 2. Check transitive services next. They may need tests or rollout coordination. 3. Open the affected-service list and confirm that the result matches the change you are planning. ## What Blast Radius does not know Blast Radius only knows what is represented in the map. It does not know: - live request volume, latency, errors, or uptime; - whether an edge is synchronous or asynchronous unless you label it; - ownership, permissions, or team boundaries; - whether two arrowheads should be treated as two graph paths; - hidden dependencies that are not represented by edges. For a useful result, add important handoffs as edges, keep their directions current, and label ambiguous connections. ## Troubleshooting ### Nothing is highlighted The focus may have no connected lines, or the lines may be outside the selected depth. Try **All**, then check the lines connected to the focus. ### The result is too large Switch to **1 hop** or **2 hops** for a smaller review. Return to **All** when you want the full connected result. ### A service appears on the wrong side Blast Radius follows the stored start and end of each line. If a service appears on the wrong side, edit the line's direction or add the correct arrowhead. Changing the line shape does not change the relationship. ### I need to edit while reviewing Turn on **Pin focus**, then select the node or line. The bottom editing controls and right inspector remain available while the focus stays fixed. --- # Source: https://canopy.8starlabs.com/docs/maps/build export const metadata = { title: "Build by hand | Canopy Docs", description: "Build a Canopy map manually for greenfield systems, services outside a repo, AI workflows, internal automations, and business processes.", alternates: { canonical: "/docs/maps/build" }, }; # Build by hand Start with a blank canvas and drop nodes one at a time. Good for greenfield systems, services not in your repo, AI workflows, internal automations, or anything you want to sketch before you build it. ## Naming your map Set the map's **name** and **description** in the **Canvas** tab of the right panel. Both have a limit and show a live character counter as you type: | Field | Limit | Notes | | ----------- | -------------------- | ------------------------------------------------------- | | Name | up to 40 characters | Shown on the canvas, in the maps list, and in exports | | Description | up to 280 characters | Optional summary shown in the maps list and share cards | The limits are enforced in the editor and again on save, so anything longer is trimmed to fit. ## Adding nodes Click **Add node** (or the `+` button in the toolbar) to open the integration picker. Search tools, services, workflows, and AI platforms - pick one and Canopy fills in the name and icon automatically. If the service isn't in the library, use a **Custom** node from the top of the picker. These carry a generic icon - database, server, compute, storage, cloud, queue, cache, notebook, workflow, approval, webhook, AI agent, background job, and more - so you can represent anything that doesn't have a brand mark. Drop one, rename it, and set its cost like any other node. To change a node's icon later, type a keyword in the **Tool / step** field in the inspector and pick a suggested mark (brand or generic). Custom nodes still count toward cost and node totals, but they're **excluded from the tool-usage stats** because they don't represent a specific vendor. Each node has the same fields in the **Inspector** panel on the right: | Field | What it does | | ------------- | ------------------------------------------------------------------------------------------------------------------- | | Name | How this service is labelled on the canvas | | Tool / step | Runtime, vendor, workflow step, or role - e.g. `Node.js · Express`, `approval`, `research agent` | | Icon | The brand or generic mark. Type a keyword and Canopy suggests matching marks from its library - click one to set it | | Purpose | One-line description shown in exports and the inspector | | Monthly cost | Attached cost rolls up to the group and workspace totals | | Billing model | Usage-based, flat, per-seat, or custom | ## Drawing edges Hover any node to reveal the **edge handle** on its right side. Drag it onto another node to draw a directed arrow - `web → api → db`. Edges describe request flow and don't count toward your node limit. Double-click any edge to add a label (`gRPC`, `webhook`, `REST`, `async`) for clarity. Hit **Auto-layout** in the toolbar to re-flow the whole graph at any time. ## Find & fix issues Press `⌘` `F` (`Ctrl` `F` on Windows) to **find a node** by name, tool, or step - start typing and pick a match to jump straight to it on the canvas. The toolbar also runs a live **map lint**. The **Issues** panel (the checklist icon in the left rail, or the ⚠ badge by the map name) flags the things a JSON paste or AI-generated map tends to leave broken: - **Dangling edges** - an edge whose source or target node doesn't exist - **Duplicate node ids** - **Unknown or missing icons** - an icon slug Canopy doesn't recognise, or none set - **Missing cost** - a node with no monthly cost (a suggestion, not an error) Click any node-scoped issue to select and centre that node. ## Keyboard shortcuts Press `?` anywhere in the editor to open this cheat-sheet (or click the keyboard icon in the toolbar). On Windows and Linux, `⌘` is `Ctrl`. | Shortcut | Action | | --------------- | ------------------------ | | `⌘` `S` | Save map | | `⌘` `Z` | Undo | | `⌘` `Shift` `Z` | Redo | | `⌘` `F` | Find a node | | `⌘` `K` | Open the command palette | | `V` | Select tool | | `H` | Pan tool | | `A` | Open Add node panel | | `I` | Open Node info panel | | `S` | Open Optimisations panel | | `B` | Toggle Blast Radius | | `C` | Open Code editor | | `,` | Open Canvas settings | | `E` | Open Download panel | | `Shift` + click | Add to selection | | `Delete` | Delete selection | | `⌘` `.` | Autocomplete (code) | | `?` | Toggle this help | | `Esc` | Close panels / search | Undo and redo also cover **canvas drags** - move a node and `⌘` `Z` puts it back. ## Combining approaches You can mix methods on the same map. A common pattern: import a repo to detect the core services, then hand-add the third-party SaaS tools (Stripe, Segment, Slack) that don't show up in a lockfile. For workflow maps, use the same canvas vocabulary: a webhook can point to an AI agent, which points to a review step, then to a CRM update or background job. Edges describe the handoff, data flow, or dependency between each step. --- # Source: https://canopy.8starlabs.com/docs/maps/edges export const metadata = { title: "Edges | Canopy Docs", description: "Connect nodes with dependency, API, workflow, event, ownership, and data-sync edges to show how a system works.", alternates: { canonical: "/docs/maps/edges" }, }; # Edges An **edge** is a directional connection between two nodes. It describes how requests, data, ownership, or events flow through your system. ## Line styles An edge is directional and can be drawn in one of four line styles. Pick what reads best for the layout: Select an edge and switch its line in the **Connection** panel, or set a map-wide default from **Canvas settings**. The choice is saved per edge in `canopy.json` as `"line": "step"`, `"smoothstep"`, `"bezier"`, or `"straight"`. ## Arrows and direction By default an edge is undirected (just a line). Select it and open the **Connection** panel to add arrowheads: - **None** - no arrowhead (an association, not a flow). - **Single** - one arrow at the target end, a directed flow (`A → B`). - **Both** - arrows at both ends, a bidirectional link (`A ↔ B`). Saved per edge as `"arrow": "none"`, `"end"`, or `"both"`. Omitting `arrow` (or setting `"none"`) keeps the classic undirected look. Blast Radius still follows the stored `source` to `target` relationship even when an edge has no visible arrowhead. See [Blast Radius](/docs/maps/blast-radius) for the full upstream and downstream model, hop controls, and a worked example. ## Labels Give an edge a short label to name what flows across it (e.g. `webhook`, `gRPC`, `read replica`). Type it in the **Connection** panel; it is drawn at the midpoint of the line and saved as `"label": "webhook"`. Clear the field to remove it. Labels hold up to **120 characters**. ### Explaining business and AI workflows Edge labels shine on **workflow maps** - business processes and AI agent pipelines - where the interesting part is _what happens between the steps_. Label each connection with the handoff, trigger, or condition so the map reads as a runbook: - **Business workflow** - `Intake form → Review agent` labelled `on submit`, `Review agent → Human approval` labelled `if confidence < 0.8`, `→ CRM` labelled `on approve`. - **AI workflow** - `Router → Vision model` labelled `image input`, `Retriever → LLM` labelled `top-k context`, `LLM → Guardrail` labelled `before send`. For a longer description of a step itself, use the node's **purpose** field (up to 160 chars); keep the edge label to the short handoff or condition so it stays readable on the canvas. Both flow straight into your `CLAUDE.md` / `AGENTS.md` exports, so an agent reads the sequence, not just the boxes. ### Styling a label Once a label is set, the **Connection** panel exposes its styling: - **Font** - `sketch` (Excalifont, the hand-drawn default), `sans`, or `mono`. All three are open-source (SIL OFL) and bundled with the app. - **Size** - 6-48 px (`"labelSize": 14`). - **Text color** - a swatch or any hex (`"labelColor": "#ef4444"`); **Default** uses a muted foreground. Saved per edge as `"labelFont"`, `"labelSize"`, and `"labelColor"`. ## Color An edge uses the animated gradient by default. Pick a swatch in the **Connection** panel to override the stroke (handy for grouping flows by concern - data vs events vs auth). Saved as `"color": "#10b981"` (any hex, rgb, or named CSS color). Choose **Default** to drop the override and return to the gradient. ## Moving dots Each edge shows a dot travelling along it to convey flow. Toggle **Moving dots** in the **Connection** panel to turn the motion on or off per edge (saved as `"animated": false` when off). While dots are on, set a **Dot color** - it defaults to **Match line** (the dot follows the edge color) but you can give it its own swatch, saved as `"dotColor": "#3b82f6"`. ## Working with edges - **Draw** - drag between node handles to connect them. - **Style** - swap an edge's line type, add arrows, a label, or a color. - **Direction** - set arrowheads to none / single / both. - **Delete** - select an edge and remove it without affecting the nodes. Edges do not count toward your node limit, and they make dependencies explicit so you can trace what depends on what across your system. In exported `architecture.md`, `CLAUDE.md`, and `AGENTS.md`, edges render as arrows so agents can parse the topology, and any **label** comes along in parentheses (`- inbox → agent (on submit)`). Bidirectional edges use `↔`. --- # Source: https://canopy.8starlabs.com/docs/maps/embed export const metadata = { title: "Embed a map | Canopy Docs", description: "Embed a live public Canopy map in a README, Notion page, Confluence document, or website with an always-current view.", alternates: { canonical: "/docs/maps/embed" }, }; # Embed a map Put a live map in a README, a Notion page, a Confluence doc, or your own site. It stays current: edit the map in Canopy and every embed updates. ## Two snippets, and they are not interchangeable **Notion, Confluence, a blog, a wiki** get an iframe. Readers can pan and zoom; nobody can edit. ```html ``` **A GitHub README** needs the image form instead: ```md [![Architecture map](https://embed.canopy.8starlabs.com/embed/map//map.svg)](https://canopy.8starlabs.com) ``` GitHub's markdown sanitizer strips ` ``` The same option works for a README image: ```md [![Architecture map](https://embed.canopy.8starlabs.com/embed/map//map.svg?theme=dark)](https://canopy.8starlabs.com) ``` The embed does not guess the parent page theme. The explicit URL keeps the interactive and image versions stable, including when a cached image is shown. ## The map must be public An embed follows the map's **sharing state**. A private map's embed returns 404, and setting a public map back to private stops every existing embed immediately. There is no separate embed link or token. Deciding to embed a map is the same decision as making it public: anyone with the URL can see it. Canopy blocks framing for dashboard pages, but the embed route intentionally allows framing from any site with `frame-ancestors *`. It is served from a separate cookieless host, can only read public map data, and is read-only. The generated iframe requests fullscreen only. ## Options | Parameter | Values | Default | | --------- | ---------------- | ------- | | `theme` | `light`, `dark` | `light` | | `spend` | `1` to show cost | hidden | Append them to either URL, e.g. `/embed/map/?theme=dark&spend=1`. Anything else is ignored. Monthly spend is **off by default** in embeds, even though a public map page shows it. An embed travels further than a page someone chose to visit - into READMEs, wikis, and search results - so turning cost on is a deliberate act. ## Attribution Every embed carries a **Made with Canopy** badge, on every plan: This differs from [exports](/docs/maps/exports), where Pro can remove the watermark: an export is your own data leaving Canopy, whereas an embed is Canopy rendering inside someone else's page. ## Sizing The iframe fills whatever box you give it. `460px` tall suits most maps; give a large map more height, or let readers zoom. The image form scales to its container like any other image. ## Why embeds are served from a different domain Embeds come from `embed.canopy.8starlabs.com`, never from the app domain. That is deliberate: an embed renders inside a page Canopy does not control, so it is served from an origin that holds **no Canopy session**. An embed cannot read your cookies, act as you, or reach the API, because on that origin there is nothing to reach with. The embed also loads no external scripts or fonts and makes no network calls of its own. --- # Source: https://canopy.8starlabs.com/docs/maps/exports export const metadata = { title: "Export formats | Canopy Docs", description: "Export a Canopy map as PNG, Markdown, CLAUDE.md, AGENTS.md, Figma, or Notion content for teams and AI tools.", alternates: { canonical: "/docs/maps/exports" }, }; # Export formats A Canopy map is portable. Export it to the formats your team and your agents already use. ## Formats - **`architecture.md`**: the canonical Markdown description of your system. - **`CLAUDE.md` / `AGENTS.md`**: AI context files that live in your repo. - **`README.png`**: a rendered diagram for your README. - **`diagram.fig`**: an editable Figma frame. - **JSON**: the structured map data: nodes, edges, positions, and metadata. - **`notion.page`**: a synced Notion doc. Every workspace can export PNG, Markdown, `CLAUDE.md`, and `AGENTS.md`. Each export carries a small "Made with Canopy" badge - always, on every plan. [Pro](/pricing) adds Figma and Notion exports. ## canopy.json ⇄ canvas Your `canopy.json` and the canvas stay in sync both ways. Describe the system as JSON and Canopy renders a live, editable map; drag the map and the `canopy.json` updates. ## Add it to your README An exported PNG is a snapshot that goes stale. An [embedded map](/docs/maps/embed) updates whenever you save, and GitHub proxies the image through its own CDN so it costs you almost nothing to serve. There's no iframe or live embed because GitHub strips `