Announcing the Terrateam REST API

We're excited to announce that comprehensive documentation for the Terrateam REST API is now publicly available.

What's Available

The API provides programmatic access to core Terrateam functionality:

• Access Token Management: Create, list, and revoke API tokens with fine-grained capability controls. Define exactly what each token can do, from reading the KV store to managing installations.

• Key-Value Store: A persistent data store that survives across workflow runs. Store configuration, feature flags, counters, or any data you need to share between operations. Supports atomic operations, versioning, and transactions.

• GitHub & GitLab Integrations: Manage installations, repositories, pull requests, and work manifests. Query dirspaces, retrieve outputs, and list workspaces programmatically.

• Stack Information: Retrieve stack details and dependencies for any pull request. Build custom reporting or integrate stack data into your monitoring systems.

• System Configuration: Access server configuration, OAuth client IDs, and manage long-running async tasks.

All endpoints include comprehensive request and response schema documentation, making integration straightforward.

Key Features

Security-First Authentication

We designed a two-step authentication model that balances security with developer experience.

First, you create a long-lived API key in the Terrateam dashboard with specific capabilities. This API key has exactly one permission: refreshing access tokens.

Then, you use that API key to obtain short-lived access tokens (60 seconds) that inherit the capabilities you selected. These short-lived tokens are what you use for actual API calls.

This approach means your long-lived credentials never touch production systems, and compromised tokens expire quickly.

Fine-Grained Capabilities

The token capabilities system lets you grant exactly the permissions each integration needs. Choose from capabilities like:

• Read and write access to the key-value store
• Creating new API access tokens
• Installation and VCS-specific scopes

Combine capabilities to create tokens with precisely the access your automation requires.

Complete Schema Documentation

Every endpoint includes full JSON schema documentation for requests and responses. You'll see exactly what fields are required, what types they accept, and what data you'll get back.

No guessing, no trial-and-error. Just clear, comprehensive documentation.

Getting Started

Creating your first API integration takes just a few steps:

Step 1: Create an API Key

Go to Settings > API Access in the Terrateam dashboard. Create a token with the capabilities your integration needs.

Step 2: Get an Access Token

Use your API key to fetch a short-lived access token:

curl -X POST https://app.terrateam.io/api/v1/access-token/refresh \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 3: Make API Calls

Use the access token for your requests:

curl -X GET https://app.terrateam.io/api/v1/whoami \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Access tokens expire after 60 seconds, so your integration will need to refresh tokens periodically. The documentation includes code examples showing how to implement automatic refresh logic.

Documentation

The complete API reference is available at docs.terrateam.io/reference/api/.

You'll find detailed documentation for every endpoint, including:

• Authentication workflows
• Request and response schemas
• Query parameters and path variables
• Example requests with curl
• Common patterns and best practices

The API documentation is organized by function (Access Tokens, KV Store, GitHub Installations, etc.) to make finding what you need straightforward.

What's Next

The REST API is currently in beta. It's stable and ready to use, but we expect to iterate based on your feedback.

We're especially interested in hearing about:

• Use cases we haven't considered
• Missing functionality that would unblock your automation
• Developer experience issues or documentation gaps
• Creative integrations you build

Reach out through our support channels or join our community Slack to share feedback.

Get Started Today

The Terrateam REST API opens up new possibilities for infrastructure automation. Whether you're building custom integrations, orchestrating complex workflows, or just want programmatic access to your infrastructure operations, the API gives you the flexibility to work the way you want.

Check out the full API documentation and start building.