1. Docs
  2. API Reference

Canopy Public API

 v1.0

Public API endpoints for machine-to-machine integrations. Authenticate with an API key via the X-API-Key header, or a JWT Bearer token.

Base URL

https://api.canopy.dev

Authentication

API Key

Used for server-to-server communication. Include in the header of your requests. 

X-API-Key: <your_api_key>
 Bearer Token

Used for user-delegated actions via OAuth 2.0 flows. 

Authorization: Bearer <token>

Your first request

Minimal working example — list identities in your account.

curl -H "X-API-Key: $CANOPY_API_KEY" https://api.canopy.dev/api/v1/identities

Response envelope

Every response follows one of a small set of predictable shapes, keyed by the top-level field.

Single item

Returns one resource wrapped in data . 

{
  "data": {
    "id": "id_01HXABC...",
    "name": "Acme Realty",
    "createdAt": "2026-04-04T01:23:45.678Z"
  }
}
 Collection

Returns an array under items , plus a pagination block when paged. 

{
  "items": [
    { "id": "id_01HXABC...", "email": "alex@acme.com" },
    { "id": "id_01HXDEF...", "email": "sam@acme.com" }
  ],
  "pagination": {
    "page": 1,
    "take": 20,
    "item_count": 47,
    "page_count": 3,
    "has_previous_page": false,
    "has_next_page": true
  }
}
 Partial success

Bulk endpoints that process items independently return 207 Multi-Status with a summary and per-item results . Each result carries its own status ( success or error ), an HTTP-like code , and either data or error . 

// HTTP 207 Multi-Status
{
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    {
      "index": 0,
      "status": "success",
      "code": 201,
      "data": { "id": "asgn_01HXABC..." }
    },
    {
      "index": 1,
      "status": "success",
      "code": 201,
      "data": { "id": "asgn_01HXDEF..." }
    },
    {
      "index": 2,
      "status": "error",
      "code": 409,
      "input": { "identity_id": "usr_3", "role_id": "role_admin" },
      "error": {
        "code": "rbac.assignment_conflict",
        "message": "Identity already has this role at this node"
      }
    }
  ]
}
 No content

Successful operations with no body return 204 No Content . Used for deletes, revocations, and side-effect-only requests. 

HTTP 204 No Content
(empty body)

Errors

Errors use standard HTTP status codes and a consistent envelope. Use the code field for programmatic handling and message as the English fallback for display.

Standard error

A machine-readable code (e.g. nodes.node_not_found ) plus the originating request's path and method. 

{
  "error": {
    "statusCode": 404,
    "code": "nodes.node_not_found",
    "message": "Organization node not found",
    "timestamp": "2026-04-04T01:23:45.678Z",
    "path": "/api/v1/nodes/abc",
    "method": "GET"
  }
}
 Validation error

Per-field messages from request-body validation are returned in details ; code is null for generic validation failures. 

{
  "error": {
    "statusCode": 400,
    "code": null,
    "message": "Validation failed",
    "timestamp": "2026-04-04T01:23:45.678Z",
    "path": "/api/v1/identities",
    "method": "POST",
    "details": [
      "email must be an email",
      "password must be longer than or equal to 8 characters"
    ]
  }
}
Error code Message
400 Validation failed — see details
401 Missing or invalid credentials
403 Authenticated, but lacks permission
404 Resource does not exist
429 Rate limit exceeded — see Retry-After header
500 Unexpected server error

Endpoints

Browse endpoints by resource group.

Resource Endpoints
API Keys 3 endpoints
Assignments 8 endpoints
Audit Events 2 endpoints
Hierarchy Schema 2 endpoints
Identities 13 endpoints
Identity Invites 6 endpoints
Nodes 11 endpoints
Permissions 7 endpoints
Roles 7 endpoints
Webhooks 5 endpoints
Environment
On this page
Canopy