API Reference
The Terrantula API is an HTTP REST API that covers the full Terrantula control plane — entity graph, cells, actions, secrets, audit, GitHub integration, and administration. It is the same API that the SDK and CLI use under the hood.
For an interactive explorer where you can browse and try every endpoint, see Scalar explorer.
Authentication
All project-scoped endpoints require a Bearer API token in the Authorization header:
Tokens have a terr_ prefix. There are two token types:
- Project API tokens — scoped to a specific project; issued under
/projects/:projectId/tokens. Use these in CI, the CLI, and service-to-service calls. - Personal tokens — org-scoped; issued via the UI or the personal tokens API. Use these for interactive access.
Webhook endpoints are an exception: they authenticate via HMAC-SHA256 (X-Hub-Signature-256 header) and never accept a Bearer token.
RBAC permissions
Every project-scoped endpoint requires a specific permission in addition to a valid token. The required permission is shown inline on each endpoint in this reference. The permission strings follow the pattern resource:action:
| Permission | Description |
|---|---|
catalog:read | Read entity types, cells, relationship types, actions, environments |
catalog:write | Mutate catalog configuration |
data:read | Read entities, relationships, action runs, drift events |
data:write | Create/update/delete entities and relationships |
apply:write | Trigger catalog applies (admin and above) |
secrets:read | List secrets (names only; values are write-only) |
secrets:write | Create and update secrets |
secrets:set-value | Update secret values |
tokens:manage | Issue and revoke project API tokens |
URL structure
Most endpoints are project-scoped and follow this pattern:
Where {orgSlug} and {orgSlug}/{projectSlug} are the organization and project slugs, respectively. Org-scoped endpoints are under /orgs/:orgId/.
Resources
The API is organized into resource groups. Each group has a dedicated reference page generated from the live spec.
| Resource | Description |
|---|---|
| EntityTypes | Entity type catalog entries — the schema for your infrastructure assets |
| Cells | Cell (pool) definitions — logical groupings of entities |
| RelationshipTypes | Relationship type catalog |
| Actions | Action definitions — parameterized operations that open PRs |
| Environments | Environment-scoped containers for entities and relationships |
| Entities | Individual infrastructure assets |
| Relationships | Typed edges between entities |
| ActionRuns | Records of action invocations |
| CatalogRevisions | Catalog revision history |
| Secrets | Encrypted project secrets |
| Apply | Catalog apply operations |
| Webhooks | Inbound GitHub webhook receiver |
| Projects | Project CRUD within an org |
| ProjectTokens | Project API token lifecycle |
| Orgs | Organization management |
| PersonalTokens | Personal API token lifecycle |
| ImportSources | Terraform state import source configuration |
| GitHub | GitHub App integration |
| AuditEvents | Audit log entries |
| AuditExport | Audit export configuration |
| DriftEvents | Drift detection events |
| Stats | Project statistics |
| GraphViews | Saved graph view configuration |
| Notifications | Notification delivery |
| UserPreferences | Per-user UI preferences |
| Admin | Administrative operations |