Spaces
A Space is the older product name for a team, not a separate
resource. The REST API’s /spaces/* alias has been removed; use the
/teams/* routes shown here. The CLI and SDK still expose some older
space names for the preview search, overview and assistant workflows.
Your existing team is the resource those interfaces address.
If you only have one team, there’s little reason to think about Spaces as a separate concept at all - the value is in the new capabilities layered on top, described below.
What’s built today
Section titled “What’s built today”Search
Section titled “Search”Free-text search across the resources Canopy already knows about for your Space (projects, environments, and other node kinds registered in the engineering graph).
canopy space search "redis" --space <id-or-slug> --kinds environment,databaseGET /teams/:id/search?q=redis&kinds=environment,databaseThis is Host-only - it doesn’t reach into Cortex-owned data.
Overview
Section titled “Overview”A read-only monitoring roll-up: recent platform events, open incidents, recent builds, and budget status for the Space, in one page. No alerts, no write path - just a dashboard.
canopy space monitor --space <id-or-slug>GET /teams/:id/overviewIn the dashboard: Spaces → (a Space) → Overview.
Registry
Section titled “Registry”The read-only registry view combines items owned by the Space: npm packages, MCP servers, templates, workflows and artifacts. It does not publish, install or modify those items.
canopy space registry --space <id-or-slug>GET /teams/{team_id}/registryThis route needs team:read.
Deploy every environment
Section titled “Deploy every environment”canopy space deploy starts a fan-out deploy and returns a deploy ID. Environments are attempted sequentially in creation
order. The next environment starts after the current one reaches a terminal build state, including failure. A failure does
not roll back earlier environments or stop later attempts; inspect each environment’s result before taking further action.
canopy space deploy --space <id-or-slug>canopy space deploy-status <space-deploy-id> --space <id-or-slug>The API needs environment:deploy:
POST /teams/{team_id}/deployGET /teams/{team_id}/deploy/{deploy_id}GET /teams/{team_id}/deploy?limit=50The POST returns 202 Accepted. A Space with no environments returns 400. The status response includes the fan-out
record and each environment’s status. There is no cross-environment rollback.
List recent fan-out runs with the GET collection route; limit defaults to 50 and is capped at 200.
Space AI assistant
Section titled “Space AI assistant”A chat surface scoped to one Space, backed by a bounded tool loop over the engineering graph (pre-bound to your team and user, so a prompt can’t re-scope itself to another Space). Answers questions like “which environments use Redis?”
canopy space ask "which environments are behind on deploys?" --space <id-or-slug>POST /teams/:id/assistant/chat{ "messages": [...] }Attaching context
Section titled “Attaching context”Add an optional context to say what the question is about. Everything in it is
resolved on the server, and only what you can read in this Organization is used.
canopy space ask "why did this fail?" \ --ref graph:environment:<environment_id> \ --ref log_excerpt:<build_id>:120-131 \ --system <system_id> --jsonPOST /teams/:id/assistant/chat{ "messages": [{ "role": "user", "content": "why did this fail?" }], "context": { "refs": [ "graph:environment:<environment_id>", { "ref": "log_excerpt:<build_id>:120-131", "origin": "explicit" } ], "focus": { "system_id": "<system_id>" } }}refsholds up to 8 entries, each at most 200 characters. A ref is a plain string (an explicit attachment) or{ "ref", "origin" }whereoriginisexplicitorinferred(what the page offered, not what you picked). Over the limit, or a wrong shape, is a 400.graph:<kind>:<id>refs attach any record of the Organization the graph knows. An environment also brings its current and last verified-healthy deployment.log_excerpt:<build_id>:<first>-<last>attaches log lines. Lines are 1-based and inclusive and number the build’s stdout then stderr, in order. Canopy re-reads the lines itself and redacts secrets as it does for build-failure analysis, so text typed into the message is never treated as a log. At most 200 lines, 500 characters a line and 12,000 characters per excerpt (24,000 per request) are sent; a longer range is cut and reported.graph:build:<id>also sends the build’s recorded outcome: its status, failure stage, failure kind and failure detail (redacted).verification:<build_id>attaches the build’s recorded post-deploy health check: status, attempts, probe target, detail (redacted) and when it was checked. It is refused like any other ref when the build is not in this Organization or no check was recorded.security_finding:<finding_id>andsecurity_remediation:<remediation_id>attach what Canopy recorded about a finding or a fix, labelled as recorded, implied or unknown, with a rule that the answer may not invent an advisory, version or state or claim exploitability. See Security findings. They are refused as not found when the record is in another Organization, in a project you cannot read, or Security findings is off.focus.system_idasks the assistant to look at that System first. It is given, in about 6,000 characters, the System’s owners and contact (or that there are none), each environment you can read with its serving and delivery state and the reason code, for production what is live and what was last verified healthy, and the changes of the last 14 days with who made them (display names only, at most 40, newest first). Every line carries a ref, and what is not available (relations to other Systems, request telemetry, logs that were not attached) is listed as such. When it does not fit, the oldest changes and then the last environments are left out andlimitationssays so. It is a focus, not a permission: you only get what you can read.- The assistant has a
system_timelinetool to read more of a System’s changes (up to 14 days). Its tools,traverseandcorrelate_commitincluded, only return records of the Organization you asked from, and of what you may read in it. - A ref you cannot read, a ref from another Organization and a ref that does not exist
all come back the same way:
included: false, reason: "not_found". Nothing from it is sent to the model.
The response keeps content and adds what the answer was based on:
{ "content": "...", "context": { "items": [{ "ref", "label", "kind", "origin", "included", "reason?", "truncated?", "line_range?" }], "focus?": {} }, "retrieved": [{ "tool", "refs", "truncated", "auth_truncated" }], "grounding": [{ "environment_ref", "current", "last_healthy" }], "limitations": ["..."]}context echoes what you attached as the server saw it, retrieved lists what each
tool call looked at (only records of this Organization), grounding is the deployment
history given for attached environments, and limitations says what could not be
established. A request without context works as before; the extra fields are simply
empty. --json prints the whole response; the text output lists the limitations after
the answer.
Returns 503 if the assistant isn’t configured for your deployment (same fail-closed behavior as Canopy’s other AI-assistant surfaces) - this isn’t a bug, it means the feature needs an API key set on the server side.
Conversations can be saved to your private history; see Saved assistant conversations.
CLI reference
Section titled “CLI reference”canopy space listcanopy space create <name>canopy space use <id-or-slug>canopy space currentcanopy space search <query> [--space <id-or-slug>] [--kinds k1,k2]canopy space monitor [--space <id-or-slug>]canopy space registry [--space <id-or-slug>]canopy space ask <question> [--space <id-or-slug>] [--ref <ref>]... [--system <id>]canopy space deploy [--space <id-or-slug>]canopy space deploy-status <space_deploy_id> [--space <id-or-slug>]What’s not built yet
Section titled “What’s not built yet”Spaces has more phases planned that aren’t live: automation triggers (binding graph events to workflows), finer Space-specific authorization beyond the existing team roles, Space-scoped API keys, cross-Space sharing, and a Cortex link-status indicator on the overview page. Custom roles are available at team scope. Don’t build against these planned capabilities.