API Reference

The Terrateam REST API allows you to programmatically interact with Terrateam installations, work manifests, repositories, and more. Use the API to integrate Terrateam into your CI/CD pipelines, build custom workflows, and automate infrastructure operations.

Beta

The API is in beta and subject to change. We recommend versioning your integrations and monitoring for updates.

Getting Started

Authentication Workflow

The Terrateam API uses a two-step authentication process:

Step 1: Create an API Key

1. Navigate to Settings > API Access in the Terrateam dashboard
2. Click Create Token
3. Provide a name and select the required capabilities
4. Copy the API key (it will only be shown once)
5. Store the API key securely

The API key is long-lived and can only be used to obtain access tokens.

Step 2: Get an Access Token

Use your API key to call the refresh endpoint and obtain an access token:

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

Response:

{
  "token": "eyJhbGc..."
}

The access token inherits the capabilities you selected when creating the API key.

Step 3: Make API Requests

Use the access token for all API requests:

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

Token Expiration

Access tokens expire after 60 seconds. You’ll need to call the refresh endpoint frequently to get new tokens for ongoing API operations.

Example: Long-Running Script

For scripts that make multiple API calls over time, you’ll need to refresh tokens regularly:

#!/bin/bash
API_KEY="your_api_key_here"

# Function to get a fresh access token
get_access_token() {
  curl -s -X POST https://app.terrateam.io/api/v1/access-token/refresh \
    -H "Authorization: Bearer $API_KEY" | jq -r '.token'
}

# Get initial token
ACCESS_TOKEN=$(get_access_token)

# Make API requests
# Refresh token every 50 seconds to be safe (before 60s expiration)
while true; do
  # Use the token
  curl -X GET https://app.terrateam.io/api/v1/whoami \
    -H "Authorization: Bearer $ACCESS_TOKEN"

  # Wait and refresh
  sleep 50
  ACCESS_TOKEN=$(get_access_token)
done

Base URL

https://app.terrateam.io

For self-hosted installations, use your custom domain.

API Categories

GitHub Installations

Manage GitHub installations, repositories, pull requests, and work manifests.

View Endpoints →

GitLab Installations

Manage GitLab installations, groups, repositories, and work manifests.

View Endpoints →

Access Tokens

Create, list, refresh, and delete API access tokens for authentication.

View Endpoints →

Key-Value Store

Store and retrieve persistent data across workflow runs using the KV store.

View Endpoints →

Authentication

Retrieve user information and manage authentication sessions.

View Endpoints →

Stacks

Retrieve stack information and dependencies for pull requests.

View Endpoints →

System & Admin

Admin operations, server configuration, task management, and system utilities.

View Endpoints →

Common Patterns

Pagination

Many list endpoints support pagination using the page and limit query parameters:

GET /api/v1/github/installations/{installation_id}/repos?limit=50&page=...

Filtering and Sorting

Use q for search queries and d for sort direction (asc or desc):

GET /api/v1/github/installations/{installation_id}/work-manifests?q=terraform&d=desc

VCS Parameter

Endpoints with {vcs} path parameter accept:

• github - For GitHub integrations
• gitlab - For GitLab integrations

Rate Limiting

API requests are rate limited to prevent abuse and ensure fair usage. Requests exceeding the limit will receive 429 Too Many Requests.

If you encounter rate limits, implement exponential backoff and retry logic in your client applications.

Error Responses

The API uses standard HTTP status codes:

Code	Description
200	Request successful
400	Bad request - Invalid parameters
403	Forbidden - Invalid or missing authentication
404	Resource not found