API
Overview
Authentication, resource model, errors, and versioning for the Catoids HTTP API.
- API
- 1 min read
Base URL and versioning
Tenant APIs are served under a /v1 prefix. Breaking contract changes bump the major path or ship under a compatibility window announced in Release notes.
Authentication
Use bearer tokens scoped to a tenant. Call whoami (or the equivalent session endpoint) to verify identity and tenant resolution before mutating resources.
Core resources
Representative resources in early releases:
| Resource | Purpose | | ----------------- | -------------------------------------------- | | Domains | Bounded contexts and publication status | | Kernels | Modular business kernel registration | | Workflows | Orchestration definitions and instances | | Decisions | Decision requests, results, and explanations | | Knowledge entries | Versioned knowledge artefacts |
Exact schemas evolve with tenant releases — prefer the SDK types pinned to your version.
Errors
Errors return structured codes and human-readable messages. Treat 4xx as client or config issues and 5xx as platform faults. Retry only when the response is marked retriable.
SDKs
The @catoids/sdk package wraps transport, auth headers, and typed resources. See Installation and the Developer quick reference.