Terracotta API

Terracotta’s API gives you standalone access to our Terraform/CDKTF analysis commands—Summary, Review, Plan, Guard, Drift, and Conversations without wiring into your repo or PR system. Each request automatically creates a new AI conversation and returns a conversationId you can continue with via the Conversations endpoint.

Authentication

Terracotta’s API requires authentication for all /tc/* endpoints. You can authenticate using either an API Key (x-api-key header) or a Bearer Token (Authorization: Bearer ...).

You must first create an account and generate an API key from the Settings → API Keys page in the Terracotta dashboard.

Get an API key

1. Sign in to the Terracotta dashboard.
2. Navigate to Settings → API Keys.
3. Click Create API Key and copy the value.

Using the API key

Option A — x-api-key header (recommended)

curl -X POST "https://api.tryterracotta.com/v1/tc/summary" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{
    "patches": [
      {
        "filePath": "main.tf",
        "patch": "@@ -1,2 +1,5 @@\n+resource \"aws_s3_bucket\" \"demo\" { bucket = \"demo-bkt\" }\n",
        "status": "modified"
      }
    ]
  }'

Option B — Bearer token

curl -X POST "https://api.tryterracotta.com/v1/tc/summary" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_BEARER_TOKEN>" \
  -d '{ "patches": [ ... ] }'

You only need one of these methods per request.

Quick Health Check

You can test connectivity without authentication:

curl "https://api.tryterracotta.com/v1/health"
# => { "ok": true }

Explore the Reference

See the full endpoint details and schemas here:

👉 Full API reference: https://docs.tryterracotta.com/reference/