API Reference

Canopy exposes a complete REST API that powers everything you can do in the web UI. You can use it to automate inventory updates, integrate with CI/CD pipelines, build custom dashboards, or pull EA data into other tools (BI, GRC, ITSM, spreadsheets).

The complete OpenAPI 3.1 specification is available in the API Endpoints section of the sidebar — every endpoint, parameter, and response shape, regenerated from the backend source on every release.

---

Base URL

All API endpoints live under the /api/v1 prefix. Your Canopy environment URL follows the pattern:

https://{your-slug}-canopy.rhizo-tech.org/api/v1

Replace {your-slug} with your organisation's slug, which appears in your Rhizo account and in the URL you use to access Canopy.

The single exception is the health endpoint, which is mounted at /api/health (no version prefix).

---

Interactive API Reference

The full OpenAPI 3.1 specification is available in the API Endpoints section of the sidebar. Each endpoint page includes an interactive playground where you can enter your bearer token and execute live requests against your Canopy environment.

The raw spec is also downloadable for code generators:

https://docs.rhizo-tech.org/api/openapi.json

note

To use the interactive playground, open any endpoint page in the API Endpoints sidebar section, enter your bearer token in the Authorization field, fill in the parameters, and click Send.

---

Authentication

All endpoints except /auth/*, the health check, and public web portals require a JSON Web Token sent in the Authorization header:

Authorization: Bearer <access_token>

Obtaining a token

POST /api/v1/auth/login with your email and password:

curl -X POST https://{your-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

The response contains an access_token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Tokens are valid for 24 hours. Use POST /api/v1/auth/refresh to extend a session without re-entering credentials.

SSO users

If your organisation uses Single Sign-On, you cannot log in with email/password via the API. Ask your Canopy administrator to create a dedicated service account with a local password for automation use.

Using the token

curl https://{your-slug}-canopy.rhizo-tech.org/api/v1/cards \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

---

Permissions

The API enforces the same RBAC rules as the web UI. Every mutating endpoint checks both the caller's app-level role and any stakeholder roles they hold on the affected card. There are no separate "API permissions" or service-account bypasses — automation scripts run with the permissions of the user whose token they use.

If a request fails with 403 Forbidden, the token is valid but the user lacks the required permission. See the Users & Roles page for the permission registry.

---

Common Endpoint Groups

The sidebar reference is the full source of truth; the table below is a quick map of the most-used groups:

Prefix	Purpose
/auth	Login, register, SSO callback, token refresh, current user info
/cards	CRUD on cards (the core entity), hierarchy, history, approval, CSV export
/relations	CRUD on relations between cards
/metamodel	Card types, fields, sections, subtypes, relation types
/reports	Dashboard KPIs, portfolio, matrix, lifecycle, dependencies, cost, data quality
/bpm	Business Process Management — diagrams, elements, flow versions, assessments
/ppm	Project Portfolio Management — initiatives, status reports, WBS, tasks, costs, risks
/turbolens	AI-powered analysis (vendors, duplicates, architecture AI)
/risks	EA Risk Register (TOGAF Phase G)
/diagrams	DrawIO diagrams
/soaw	Statement of Architecture Work documents
/adr	Architecture Decision Records
/users, /roles	User and role administration (admin only)
/settings	Application settings (logo, currency, SMTP, AI, module toggles)
/servicenow	Bi-directional ServiceNow CMDB sync
/events, /notifications	Audit trail and user notifications (incl. SSE stream)

---

Pagination, Filtering, and Sorting

List endpoints accept a consistent set of query parameters:

Parameter	Description
page	Page number (1-based)
page_size	Items per page (default 50, max 200)
sort_by	Field to sort by (e.g. name, updated_at)
sort_dir	asc or desc
search	Free-text filter (where supported)

Resource-specific filters are documented per endpoint in the sidebar reference (e.g. /cards accepts type, status, parent_id, approval_status).

---

Real-Time Events (Server-Sent Events)

GET /api/v1/events/stream is a long-lived SSE connection that pushes events as they happen (card created, updated, approved, etc.). The web UI uses it to refresh badges and lists without polling. Any HTTP client that supports SSE can subscribe — useful for building real-time dashboards or external notification bridges.

---

Code Generation

Because the API is fully described by OpenAPI 3.1, you can generate type-safe clients in any major language:

# Download the schema
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json

# Generate a Python client
openapi-generator-cli generate \
  -i canopy-openapi.json \
  -g python \
  -o ./canopy-client-py

# ...or TypeScript, Go, Java, C#, etc.

For Python automation, the easiest path is usually httpx or requests with hand-written calls — the API is small enough that a generator is rarely worth the dependency.

---

Rate Limiting

Auth-sensitive endpoints (login, register, password reset) are rate-limited to protect against brute-force attacks. Other endpoints are not currently rate-limited; for heavy automation scripts, implement client-side throttling.

---

Versioning and Stability

• The API is versioned via the /api/v1 prefix. A breaking change would introduce /api/v2 alongside it.
• Within v1, additive changes (new endpoints, new optional fields) can ship in minor and patch releases. Removals or contract changes are reserved for a major version bump.
• The current version is reported by GET /api/health so you can detect upgrades from automation.

---

Troubleshooting

Issue	Solution
401 Unauthorized	Token is missing, malformed, or expired. Re-authenticate via /auth/login or /auth/refresh.
403 Forbidden	Token is valid but the user lacks the required permission. Check the user's role in Users & Roles.
422 Unprocessable Entity	Pydantic validation failed. The response body lists which fields are invalid and why.