SDK Reference
@canopy/sdk is a resource-typed TypeScript/JavaScript client for the
Canopy Host API. It lives at sdk/packages/sdk in the monorepo and wraps
@canopy/sdk-core’s HTTP client (retries, idempotency keys, cursor
pagination) with one class per API resource.
Related packages in the same sdk/ workspace, not covered on this page:
@canopy/sdk-core (shared client primitives, used internally),
@canopy/analytics (framework-neutral analytics), @canopy/cortex-sdk
(the typed client for the Cortex API, including SSE streaming),
@canopy/features (the platform-feature manifest -
see Platform Features).
Install
Section titled “Install”canopy registry login --scope @canopynpm install @canopy/sdk @canopy/cortex-sdkThese packages use Canopy’s restricted npm registry. The login command writes
registry credentials to the project .npmrc; see Package Registry
for details. Keep .npmrc credentials out of source control.
Analytics and runtime packages
Section titled “Analytics and runtime packages”The SDK workspace also publishes @canopy/analytics for event collection
and @canopy/runtime for release metadata, an optional health handler, and
opt-in OpenTelemetry tracing. Both packages are installed from the same
restricted registry.
Analytics
Section titled “Analytics”@canopy/analytics sends pageviews, clicks, custom events and Core Web Vitals to Canopy, which stores and shows them on the
environment’s Monitoring page. An app hosted on Canopy needs no key, environment id or environment variable: Canopy finds the
environment from the page’s verified domain. See Analytics.
import { CanopyAnalytics } from "@canopy/analytics/next";
<CanopyAnalytics />Runtime metadata, health and tracing
Section titled “Runtime metadata, health and tracing”@canopy/runtime reads the release ID, artifact digest, environment ID and
Git SHA injected into Canopy deployments. It also exports a Fetch API health
handler and an opt-in OpenTelemetry Node SDK integration:
import { createHealthHandler, getReleaseInfo, initOtel } from "@canopy/runtime";
const release = getReleaseInfo();const health = createHealthHandler({ readinessCheck: async () => true });
if (process.env.CANOPY_RUNTIME_OTEL === "true") { await initOtel();}Mount the handler using your framework’s Fetch Request/Response adapter.
It returns 503 when the readiness callback returns false; a thrown error
propagates. It does not configure a Canopy health check. initOtel() starts
only when CANOPY_RUNTIME_OTEL=true, exports OTLP/HTTP traces to
OTEL_EXPORTER_OTLP_ENDPOINT (default http://localhost:4318), and should
run before application modules that need auto-instrumentation are imported.
Authenticate
Section titled “Authenticate”import { createCanopySDK } from "@canopy/sdk";
const sdk = createCanopySDK({ apiKey: process.env.CANOPY_API_KEY, // or: token: "..."});There’s no env-var auto-detection - baseUrl (default
https://api.canopy.pm) and apiKey/token are always passed
explicitly. Create an API key from Account → API Keys in the
dashboard, or canopy keys create <name>.
export type CanopySDKOptions = { baseUrl?: string; // default "https://api.canopy.pm" apiKey?: string; // sent as `Authorization: Bearer <apiKey>` token?: string; // alias for apiKey environmentId?: string; defaultHeaders?: Record<string, string>; debug?: boolean; timeoutMs?: number; // default 8_000 maxRetries?: number; // default 2};Non-GET requests get an auto-generated Idempotency-Key (a fresh one
per call, reused across that call’s own retries) unless you pass your
own via a call’s options.idempotencyKey. Requests retry with
exponential backoff on 429/5xx/network errors up to maxRetries.
Failures throw CanopyApiError with status, body, and retryable.
GET /projects returns 50 projects per page. sdk.projects.list() follows
the pages for you and returns every project; use listPage() to read one
page at a time:
const projects = await sdk.projects.list(); // every project
let page = await sdk.projects.listPage({ limit: 25 });while (true) { for (const project of page.projects) { // ... } if (!page.nextCursor) break; page = await sdk.projects.listPage({ limit: 25, cursor: page.nextCursor });}Most other list() calls below return an array directly; check the
resource’s own return type.
Resources
Section titled “Resources”Every resource is a property on the client: sdk.<resource>.<method>().
This page is a selected resource overview, not a generated complete
operation inventory. The source manifests currently declare
@canopy/sdk 0.94.0 and @canopy/cortex-sdk 0.17.0. Check the
Canopy package registry when selecting a release because published
versions may move ahead of this checkout. Operation-level CI now detects
route and SDK mapping drift, but the current parity report still records
unmapped operations and does not prove semantic type or authorization parity.
The resource blocks below are method examples, not standalone programs.
Identifiers such as teamId, environmentId and buildId come from
resources you have already created or read. For a complete runnable
workflow, start with the initialization example above and use the
resource methods’ declared types in your editor.
Core: projects, environments, deploys
Section titled “Core: projects, environments, deploys”await sdk.projects.list(); // every project, following pagesawait sdk.projects.listPage({ limit: 25 }); // one page: { projects, nextCursor }await sdk.projects.get(idOrSlug); // one project; throws CanopyApiError 404 if noneawait sdk.projects.create({ name, teamId });await sdk.projects.delete(projectId, projectSlug); // confirm: the project's slug; 409 confirmation_required otherwiseawait sdk.projects.deployTemplate(projectId, templateId);
const favorites = await sdk.account.favorites();const favoritedProjects = await sdk.projects.favorites();await sdk.account.favoriteProject(projectId);await sdk.account.unfavoriteProject(projectId);
await sdk.environments.get(environmentId);await sdk.environments.create(projectId, options); // repository/branch/template/etcawait sdk.environments.update(environmentId, options);await sdk.environments.delete(environmentId);await sdk.environments.runtimeLogs(environmentId, { lines: 100 }); // preview: customer container stdout/stderrawait sdk.environments.repositories.list(environmentId); // preview, host.multi_repository: also attach / update / detachawait sdk.environments.source.repositories(environmentId); // preview, host.source: read-only browsing and comparison, see Canopy Sourceawait sdk.environments.deployAndWait(environmentId, { pollIntervalMs: 1_000, pollTimeoutMs: 60_000 });
await sdk.builds.list(environmentId);await sdk.builds.get(environmentId, buildId);await sdk.builds.create(environmentId);await sdk.builds.cancel(environmentId, buildId, environmentSlug);await sdk.builds.rollback(environmentId, buildId, environmentSlug);await sdk.builds.trace(environmentId, buildId); // {traceId, signozUrl}await sdk.builds.deployApproval(environmentId, buildId, "approve");await sdk.builds.streamLogs(environmentId, buildId, onEvent); // raw SSEawait sdk.builds.logEvents(environmentId, buildId); // async iterator, resumable
await sdk.builds.listRecent({ teamId, projectId, status: "failed", kind: "package" }); // {builds, nextCursor}: the caller's builds across their teams, filteredawait sdk.teams.activity(teamId, { categories: ["imported_ci"], projectId, since }); // {items, nextCursor, categories}: the Organization's curated history, filteredawait sdk.projects.builds(projectId); // {builds, nextCursor}: recent builds across the project's environmentsawait sdk.teams.incidents(teamId); // {incidents, nextCursor}: active firstawait sdk.teams.changeEvents(teamId); // async iterator: what changed in the team, resumable
await sdk.variables.list(environmentId);await sdk.variables.set(environmentId, name, value);await sdk.variables.update(environmentId, id, name, value);await sdk.variables.delete(environmentId, id, name);await sdk.variables.setMany(environmentId, { NAME: "value" });
await sdk.domains.list(environmentId);await sdk.domains.create(environmentId, domain);await sdk.domains.delete(environmentId, domainId);await sdk.domains.enableSsl(environmentId);
await sdk.storage.list(environmentId);await sdk.storage.delete(environmentId, storageMountId);
await sdk.buildSteps.list(environmentId);await sdk.buildSteps.add(environmentId, command);await sdk.buildSteps.delete(environmentId, stepId);await sdk.buildSteps.move(environmentId, stepId, "up");
await sdk.webhooks.list(environmentId);await sdk.webhooks.delete(environmentId, hookId);await sdk.webhooks.deliveries(environmentId); // Canopy's own inbound-delivery ledger
await sdk.templates.list();await sdk.templates.get(templateId);await sdk.templates.create({ name: "Shop", slug: "shop", repository: "acme/shop", visibility: "private" });await sdk.templates.createFromEnvironment(environmentId, { name: "Shop template" });await sdk.templates.update(templateId, { name: "Updated shop" });await sdk.templates.delete(templateId);await sdk.templates.resync(templateId);await sdk.templates.replaceServices(templateId, services);Services and workers
Section titled “Services and workers”sdk.appServices operates the services of an environment: list, listByKind, listWorkers, get, create, update,
delete, state (what the service is doing now, with the age of the Grove’s report), scale, restart, logs (with
previous for the last crashed container) and runCommand (a one-off command in the service’s own process).
environments.create takes kind: "worker", and environments.run, listJobs and runtimeLogs take appServiceId.
Compute jobs
Section titled “Compute jobs”Compute jobs run ordered steps on Canopy workers. See the Compute Jobs guide for isolation, repository checkout, secret handling, placement and limits.
const job = await sdk.computeJobs.submit({ teamId, clientReference: "nightly-2026-11-02", labels: { owner: "ml" }, steps: [{ name: "check", image: "ghcr.io/acme/checker@sha256:<digest>", run: "./check.sh" }],});
const existing = await sdk.computeJobs.getByClientReference(teamId, "nightly-2026-11-02");const page = await sdk.computeJobs.list({ teamId, clientReference: "nightly-2026-11-02" });const current = await sdk.computeJobs.get(job.id);await sdk.computeJobs.cancel(job.id);clientReference lets a team safely find a job after a timed-out submit.
Submitting the same request with that reference returns the existing job; a
different request with the same reference returns a conflict. getByClientReference
returns null when no matching job exists. Cancellation remains in cancelling
until the worker confirms all steps have stopped. The caller needs the team’s
compute:submit permission to submit or cancel and compute:read to list or read.
Teams, account, billing
Section titled “Teams, account, billing”await sdk.teams.list();await sdk.teams.create(name, members);await sdk.teams.update(teamId, { name: "Platform team" });await sdk.teams.delete(teamId);await sdk.teams.getCortexOrg(teamId); // null when no Cortex organization is linkedawait sdk.teams.linkCortexOrg(teamId, cortexOrgId); // admin; caller must belong to the Cortex organizationawait sdk.teams.unlinkCortexOrg(teamId);await sdk.teams.billing(teamId);await sdk.teams.inviteMember(teamId, email, "developer");await sdk.teams.acceptInvite(token);await sdk.teams.revokeInvite(teamId, inviteId);await sdk.teams.updateMemberRole(teamId, userId, role);await sdk.teams.removeMember(teamId, userId);await sdk.teams.setFailureSignatureSharing(teamId, enabled); // opt-in, off by defaultawait sdk.teams.listFailureSignatures(teamId);await sdk.teams.setDebtBenchmarkSharing(teamId, enabled);
await sdk.account.whoami();await sdk.account.plan();await sdk.account.updateUsername(username);await sdk.account.totpStatus(); // .totpEnroll() .totpConfirm(code) .totpDisable()await sdk.account.changePassword(currentPassword, newPassword);
await sdk.apiKeys.list();await sdk.apiKeys.create(name);await sdk.apiKeys.revoke(id);
await sdk.billing.checkout({ plan, successUrl, cancelUrl });await sdk.billing.portal();await sdk.plans.list();await sdk.repositories.list();Releases, artifacts, policies
Section titled “Releases, artifacts, policies”await sdk.releases.list(projectId);await sdk.releases.get(projectId, releaseId);await sdk.releases.create(projectId, { version: "1.0.0", artifactIds: [] });
await sdk.artifacts.list(teamId);await sdk.artifacts.get(artifactId);await sdk.artifacts.impact(teamId, { digest: "sha256:example" }); // exactly one selectorawait sdk.artifacts.lineage(artifactId);await sdk.artifacts.attestations(artifactId); // Vault-signed, not Sigstore-keylessawait sdk.artifacts.passport(artifactId); // 404 = job hasn't run yetawait sdk.artifacts.attestEvaluation(teamId, artifactId, { suiteId, suiteName, score, evaluatedAt, methodologyVersion, caseResults });
await sdk.promotions.list(environmentId);await sdk.promotions.create(environmentId, releaseId); // status stays 'pending'await sdk.promotions.approve(environmentId, promotionId);
await sdk.policies.list(teamId);await sdk.policies.get(teamId, policyId);await sdk.policies.create(teamId, { name: "Production policy", document: {} });await sdk.policies.updateDocument(teamId, policyId, document);await sdk.policies.enable(teamId, policyId); // .disable(...)await sdk.policies.simulate(teamId, policyId); // replays without blockingawait sdk.policies.decisions(teamId, policyId);Canopy Connect (CI)
Section titled “Canopy Connect (CI)”See Canopy Connect for the full lifecycle. SDK surface:
await sdk.ci.listConnections(teamId);await sdk.ci.createConnection(teamId, { provider, repositoryHost, repositoryPath });await sdk.ci.getConnection(connectionId);await sdk.ci.updateConnection(connectionId, { defaultBranch: "main" });await sdk.ci.deleteConnection(connectionId);await sdk.ci.listPipelines(connectionId);await sdk.ci.listRunsForPipeline(pipelineId);await sdk.ci.getRun(runId);await sdk.ci.listRunJobs(runId);await sdk.ci.report({ ciConnectionId, externalRunId }); // idempotentawait sdk.ci.reportJobs(runId, jobs);await sdk.ci.complete(runId, status);await sdk.ci.reportAndWait(data);
await sdk.timeline.get(environmentId); // unified build+CI timelineawait sdk.systems.list(teamId); // {systems, healthCounts}: every System with its health, reason_code, last activity and last deploymentawait sdk.systems.activity(systemId, { limit: 8 }); // {items, nextCursor}: recent changes of the System's environmentsawait sdk.systems.timeline(systemId, { days: 7 }); // {items, nextCursor, window}: changes with who did them and the groups that own themawait sdk.systems.setMemberRole(systemId, environmentId, 'production'); // or null to go back to the derived roleawait sdk.systems.owners(systemId); // {owners, contact, contactSource}: who owns it and where to reach themawait sdk.systems.addOwner(systemId, { groupId }); // or { userId }; owning grants no accessawait sdk.access.grant(teamId, { groupId, projectId, role: 'developer' }); // role bindings; also list, forGroup, explain, grantOwners, revokeawait sdk.groups.createKey(groupId, { name: 'deploy bot', resourceScope: `graph:project:${projectId}`, capabilities: ['environment:deploy'], expiresAt }); // a key that belongs to the group; also keys, revokeKeyawait sdk.groups.createChannel(groupId, { url, eventTypes: ['build.failed'] }); // a webhook for the group's Systems; also channels, removeChannelawait sdk.systems.addWatcher(systemId, { userId }); // watchers hear about builds and deploys without owningawait sdk.systems.mine(teamId); // the Systems you own or watch, directly or through a groupRegistry, marketplace, MCP hosting, generations
Section titled “Registry, marketplace, MCP hosting, generations”await sdk.registryNamespaces.list(teamId);await sdk.registryNamespaces.create(teamId, scope);await sdk.registryNamespaces.requestVerification(teamId, namespaceId, domain);await sdk.registryPackages.get(scope, name);await sdk.registryPackages.stats(scope, name);await sdk.registryPackages.dailyPulls(scope, name, version);
await sdk.workflows.list(teamId); // note: catalog.ts exports WorkflowsResourceawait sdk.workflows.get(teamId, workflowId);await sdk.workflows.create(teamId, { namespaceId, name, slug });await sdk.workflows.publishVersion(teamId, workflowId, { version, steps });await sdk.workflows.search(teamId);await sdk.workflows.listInstallations(teamId);await sdk.workflows.install(teamId, { workflowId, grantedPermissions });await sdk.workflows.uninstall(teamId, workflowId);await sdk.workflows.run(teamId, installationId);
await sdk.mcpHosting.list(teamId);await sdk.mcpHosting.create(teamId, { namespaceId, name, slug });await sdk.mcpHosting.createVersion(teamId, serverId, { version, artifactId, manifest });await sdk.mcpHosting.publish(teamId, serverId, versionId);await sdk.mcpHosting.start(teamId, serverId); // .stop(...)await sdk.mcpHosting.setCredential(teamId, serverId, keyName, value);await sdk.mcpHosting.invoke(teamId, serverId, toolName);See MCP for what “hosted MCP server” means here - a REST tool-invocation marketplace, not a connection to Canopy’s own MCP servers.
await sdk.apiSpecs.list(projectId);await sdk.apiSpecs.create(projectId, { source: "url" });await sdk.generations.list(projectId);await sdk.generations.get(projectId, generationId);await sdk.generations.create(projectId, { target: "sdk-typescript", specSource });await sdk.mcpCatalog.list(teamId); // { generated, hosted }Spaces, engineering graph (preview)
Section titled “Spaces, engineering graph (preview)”Both are lifecycle: 'preview' per the Platform Features registry - stable enough to build against, but the shape may still change.
await sdk.spaces.list();await sdk.spaces.create(name);await sdk.spaces.update(spaceId, { name: "Operations" });await sdk.spaces.search(spaceId, query);await sdk.spaces.overview(spaceId);await sdk.spaces.ai(spaceId, messages); // 503 if not configuredawait sdk.spaces.ai(spaceId, messages, { context: { refs: [`graph:environment:${environmentId}`, `log_excerpt:${buildId}:120-131`], focus: { system_id: systemId } },}); // result adds context, retrieved, grounding, limitationsawait sdk.spaces.registry(spaceId); // read-only itemsconst deploy = await sdk.teams.deploySpace(spaceId); // 202; fan-out is asynchronousawait sdk.teams.getSpaceDeploy(spaceId, deploy.space_deploy.id);await sdk.teams.listSpaceDeploys(spaceId, 20);
// or, pre-bound to one space:const space = sdk.space(spaceId);await space.projects.list();await space.search(query);await space.overview();await space.ai(messages);await space.registry();
await sdk.graph.node(ref); // ref like "graph:environment:<id>"await sdk.graph.edges(ref); // default depth is clamped server-side to 0-3await sdk.graph.commit(sha);See Spaces for what’s actually built today.
Cost, budgets, compliance, residency, incidents, recommendations, maintenance
Section titled “Cost, budgets, compliance, residency, incidents, recommendations, maintenance”await sdk.costs.summary(teamId, { since: "2026-10-01", until: "2026-10-31" });await sdk.costs.anomalies(teamId);await sdk.costs.exportJson(teamId, options); // .exportCsv(...)await sdk.costs.listCreditLedger(teamId);await sdk.costs.creditBalance(teamId);await sdk.costs.createCreditCheckout(teamId, { amountCents, successUrl, cancelUrl });
await sdk.budgets.list(teamId);await sdk.budgets.set(teamId, { monthlyLimit: 500, currency: "EUR" });await sdk.budgets.delete(teamId, budgetId);
// PREVIEW (unstable) - threshold alerts over a fixed metric vocabulary:// open_incidents_count, budget_percent_used, deploy_lag_minutes,// failed_ci_runs_on_default_branch.await sdk.alerts.list(teamId);await sdk.alerts.create(teamId, { name, metric, threshold, channel });await sdk.alerts.delete(teamId, ruleId);await sdk.alerts.events(teamId);
await sdk.compliance.list(teamId);await sdk.compliance.assemble(teamId, periodStart, periodEnd); // async jobawait sdk.compliance.get(teamId, packageId);await sdk.compliance.markLegalReviewed(teamId, packageId);await sdk.compliance.export(teamId, packageId); // 403 until legal-reviewed
await sdk.residency.listForEnvironment(environmentId);await sdk.residency.attestEnvironment(environmentId);await sdk.residency.listForArtifact(artifactId);await sdk.residency.attestArtifact(artifactId);
await sdk.incidents.list(environmentId);await sdk.incidents.get(environmentId, incidentId);await sdk.incidents.mitigate(environmentId, incidentId); // .resolve(...) .dismiss(...)
await sdk.recommendations.list(environmentId);await sdk.recommendations.inbox(teamId);await sdk.recommendations.apply(environmentId, recommendationId); // .dismiss(...) .revert(...)
await sdk.maintenance.listTasks(teamId, repositoryId);await sdk.maintenance.updateSettings(teamId, repositoryId, category, { enabled: true });await sdk.maintenance.triggerRun(teamId, repositoryId, { category, proposal, estimatedCostCents });Several of these back currently-disabled platform features
(host.automation.maintenance,
host.incidents) - calling them today against production will succeed
at the HTTP layer but the underlying capability may be inert or return
empty data. Check Platform Features before
building against one of these.
Agents, SSO/SCIM, audit, notifications
Section titled “Agents, SSO/SCIM, audit, notifications”await sdk.agents.list(teamId);await sdk.agents.create(teamId, { name, kind, permissions });await sdk.agents.setEnabled(teamId, agentId, enabled);await sdk.agents.issueKey(teamId, agentId); // plaintext key shown onceawait sdk.agents.issueApprovalToken(teamId, agentId, { action, resourceId });await sdk.agents.runs(teamId, agentId);
await sdk.sso.get(teamId); // null if not configuredawait sdk.sso.upsert(teamId, { provider: "generic", idp_entity_id: "https://idp.example.com/entity", idp_sso_url: "https://idp.example.com/sso", idp_certificate: "<PEM certificate>", allowed_email_domains: ["example.com"],});await sdk.sso.setEnabled(teamId, enabled);await sdk.sso.rotateScimToken(teamId); // plaintext, onceawait sdk.sso.revokeScimToken(teamId);
await sdk.audit.list(teamId);await sdk.audit.verify(teamId); // verifies the whole hash-chained ledgerawait sdk.audit.export(teamId, onLine);
await sdk.notifications.list({ limit: 20, offset: 0 });await sdk.notifications.markRead(id);await sdk.notifications.markAllRead();System information
Section titled “System information”await sdk.systemInformation.list(); // GET /me/system-informationawait sdk.systemInformation.seen(id);await sdk.systemInformation.dismiss(id); // 409 not_dismissible for a blocking actionawait sdk.systemInformation.snooze(id, until); // string or Date; 24 hours at most for a blocking actionawait sdk.systemInformation.team.create(teamId, { title: "Deploy freeze", severity: "warning" }); // team:manageawait sdk.systemInformation.team.list(teamId, { status: "active", limit: 20, offset: 0 });await sdk.systemInformation.team.end(teamId, id);See System information. Staff-only announcement administration is covered by the protected internal guide.
Platform Features
Section titled “Platform Features”await sdk.platformFeatures.resolved(); // public - GET /platform-features/resolvedSee Platform Features for customer availability. Staff-only administration is covered by the protected internal guide.
Cortex SDK
Section titled “Cortex SDK”Install @canopy/cortex-sdk separately from the Host SDK. The Cortex client
uses the Cortex API base URL by default; orgId sets the X-Cortex-Org
selection header, and the API key still determines which organizations and
operations the caller may access.
import { createCortexSDK } from "@canopy/cortex-sdk";
const cortex = createCortexSDK({ apiKey: process.env.CORTEX_API_KEY!, orgId: Number(process.env.CORTEX_ORG_ID),});
const spaces = await cortex.knowledgeSpaces.list(productInstanceId);const answer = await cortex.knowledgeSpaces.ask(spaces[0].id, "What is in these docs?");The example assumes productInstanceId names an instance accessible to the
API key and that the listed space already has ingested documents. ask
returns an answer with citations and retrieved chunks. For a custom
retrieval flow, use knowledgeSpaces.retrieve; for token-by-token output,
use responses.stream(conversationId, productInstanceId, content, onEvent).
The stream emits start, token, done or error events. These methods remain
subject to the Cortex API key’s organization scope and enabled capabilities.
The SDK does not currently expose the multipart document-upload endpoints;
use the Cortex CLI or documented API upload flow for ingestion.
Queued Cortex agent runs can be cancelled through the SDK. A started run cannot be cancelled by this operation and returns a conflict:
const run = await cortex.agentRuns.get(runId);if (run.cancellable) await cortex.agentRuns.cancel(runId);The package also contains wrappers for some experimental or internal surfaces. Evaluation suites, agent runs and runtime state are experimental and can be disabled per deployment; training resources are planned and internal. A wrapper’s presence is not an availability or support guarantee. See Cortex capabilities and availability.
Scope notes
Section titled “Scope notes”- Staff-only admin routes with little SDK-consumer value (host-scripts,
network-selftest) are deliberately not wrapped - use
the
arboristcommands for those. - Some resources -
spaces,graph, and anything backing a currently-disabled feature - are genuinely less stable than the rest. Treat them as preview APIs, not a guaranteed-stable contract.