Skip to content

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).

Terminal window
canopy registry login --scope @canopy
npm install @canopy/sdk @canopy/cortex-sdk

These 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.

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.

@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 />

@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.

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.

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.

await sdk.projects.list(); // every project, following pages
await sdk.projects.listPage({ limit: 25 }); // one page: { projects, nextCursor }
await sdk.projects.get(idOrSlug); // one project; throws CanopyApiError 404 if none
await sdk.projects.create({ name, teamId });
await sdk.projects.delete(projectId, projectSlug); // confirm: the project's slug; 409 confirmation_required otherwise
await 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/etc
await sdk.environments.update(environmentId, options);
await sdk.environments.delete(environmentId);
await sdk.environments.runtimeLogs(environmentId, { lines: 100 }); // preview: customer container stdout/stderr
await sdk.environments.repositories.list(environmentId); // preview, host.multi_repository: also attach / update / detach
await sdk.environments.source.repositories(environmentId); // preview, host.source: read-only browsing and comparison, see Canopy Source
await 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 SSE
await 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, filtered
await sdk.teams.activity(teamId, { categories: ["imported_ci"], projectId, since }); // {items, nextCursor, categories}: the Organization's curated history, filtered
await sdk.projects.builds(projectId); // {builds, nextCursor}: recent builds across the project's environments
await sdk.teams.incidents(teamId); // {incidents, nextCursor}: active first
await 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);

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 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.

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 linked
await sdk.teams.linkCortexOrg(teamId, cortexOrgId); // admin; caller must belong to the Cortex organization
await 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 default
await 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();
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 selector
await sdk.artifacts.lineage(artifactId);
await sdk.artifacts.attestations(artifactId); // Vault-signed, not Sigstore-keyless
await sdk.artifacts.passport(artifactId); // 404 = job hasn't run yet
await 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 blocking
await sdk.policies.decisions(teamId, policyId);

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 }); // idempotent
await sdk.ci.reportJobs(runId, jobs);
await sdk.ci.complete(runId, status);
await sdk.ci.reportAndWait(data);
await sdk.timeline.get(environmentId); // unified build+CI timeline
await sdk.systems.list(teamId); // {systems, healthCounts}: every System with its health, reason_code, last activity and last deployment
await sdk.systems.activity(systemId, { limit: 8 }); // {items, nextCursor}: recent changes of the System's environments
await sdk.systems.timeline(systemId, { days: 7 }); // {items, nextCursor, window}: changes with who did them and the groups that own them
await sdk.systems.setMemberRole(systemId, environmentId, 'production'); // or null to go back to the derived role
await sdk.systems.owners(systemId); // {owners, contact, contactSource}: who owns it and where to reach them
await sdk.systems.addOwner(systemId, { groupId }); // or { userId }; owning grants no access
await sdk.access.grant(teamId, { groupId, projectId, role: 'developer' }); // role bindings; also list, forGroup, explain, grantOwners, revoke
await sdk.groups.createKey(groupId, { name: 'deploy bot', resourceScope: `graph:project:${projectId}`, capabilities: ['environment:deploy'], expiresAt }); // a key that belongs to the group; also keys, revokeKey
await sdk.groups.createChannel(groupId, { url, eventTypes: ['build.failed'] }); // a webhook for the group's Systems; also channels, removeChannel
await sdk.systems.addWatcher(systemId, { userId }); // watchers hear about builds and deploys without owning
await sdk.systems.mine(teamId); // the Systems you own or watch, directly or through a group

Registry, 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 WorkflowsResource
await 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 }

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 configured
await sdk.spaces.ai(spaceId, messages, {
context: { refs: [`graph:environment:${environmentId}`, `log_excerpt:${buildId}:120-131`], focus: { system_id: systemId } },
}); // result adds context, retrieved, grounding, limitations
await sdk.spaces.registry(spaceId); // read-only items
const deploy = await sdk.teams.deploySpace(spaceId); // 202; fan-out is asynchronous
await 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-3
await 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 job
await 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.

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 once
await sdk.agents.issueApprovalToken(teamId, agentId, { action, resourceId });
await sdk.agents.runs(teamId, agentId);
await sdk.sso.get(teamId); // null if not configured
await 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, once
await sdk.sso.revokeScimToken(teamId);
await sdk.audit.list(teamId);
await sdk.audit.verify(teamId); // verifies the whole hash-chained ledger
await sdk.audit.export(teamId, onLine);
await sdk.notifications.list({ limit: 20, offset: 0 });
await sdk.notifications.markRead(id);
await sdk.notifications.markAllRead();
await sdk.systemInformation.list(); // GET /me/system-information
await sdk.systemInformation.seen(id);
await sdk.systemInformation.dismiss(id); // 409 not_dismissible for a blocking action
await sdk.systemInformation.snooze(id, until); // string or Date; 24 hours at most for a blocking action
await sdk.systemInformation.team.create(teamId, { title: "Deploy freeze", severity: "warning" }); // team:manage
await 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.

await sdk.platformFeatures.resolved(); // public - GET /platform-features/resolved

See Platform Features for customer availability. Staff-only administration is covered by the protected internal guide.

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.

  • Staff-only admin routes with little SDK-consumer value (host-scripts, network-selftest) are deliberately not wrapped - use the arborist commands 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.