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 the catalog document — entity types, cells, relationship types, actions, deployment targets and sets, secret declarations — plus catalog revisions |
data:read | Read entities, relationships, action runs, drift events |
actions:trigger | Trigger an action; actions:cancel, observations:write, metrics:write, drift:resolve, conformance:triage, import-sources:write, relationships:finalize are the rest of the write tier |
apply:write | Write the catalog — every declaration change is an apply (admin and above) |
secrets:read | Read which secrets have a value set; values themselves are write-only |
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 |
| Import Sources | Registered external sources entities are imported from — cross-source drift, rescans, drift proposals |
| 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 |