AtlantasAtlantasAPI Documentation

API Reference

The Atlantas REST API gives both human engineers and AI agents full control over the Terraform lifecycle. Every operation available in the dashboard is accessible programmatically.

Base URL

https://api.atlantascloud.com/api/v1

Authentication

All endpoints require a Bearer token: either a JWT from login or a scoped API token.

Header

Authorization: Bearer <token>
POST/auth/login

Authenticate with email and password. Returns a JWT access token.

Request Body

{ "email": "you@company.com", "password": "..." }

Response

{ "access_token": "eyJ...", "token_type": "bearer" }
GET/auth/me

Get the authenticated user's profile.

Response

{ "id": "uuid", "tenant_id": "uuid", "email": "...",
  "name": "...", "role": "admin", "is_active": true }
POST/auth/register

Register a new user in the tenant. Admin only.

Request Body

{ "email": "new@company.com", "password": "...",
  "name": "New User", "role": "member" }

Rate Limits

Rate limits are applied per API token. Exceeding limits returns HTTP 429.

Starter
100 req/min
Team
1,000 req/min
Enterprise
Unlimited

Instances

Manage Atlantis deployments. Each instance runs in its own isolated environment.

GET/instances

List all instances in the tenant.

Response

[{ "id": "uuid", "name": "infra-prod", "status": "running",
   "version": "v0.28.5", "config_json": {...} }]
POST/instances

Create a new Atlantis instance.

Request Body

{ "name": "infra-prod", "version": "v0.28.5",
  "config_json": { "uiReplicas": 1, "serverReplicas": 1 } }
GET/instances/{id}

Get instance details.

PUT/instances/{id}

Update instance configuration.

Request Body

{ "status": "running", "version": "v0.29.0" }
DELETE/instances/{id}

Delete an instance and its associated resources.

Environments

Cloud environments linked to instances. Supports AWS, GCP, Azure, Hetzner, and DigitalOcean.

GET/environments

List all environments.

POST/environments

Create an environment.

Request Body

{ "name": "production", "cloud_provider": "aws",
  "region": "eu-west-1", "terraform_workspace": "prod",
  "repository_url": "https://github.com/org/infra" }
PUT/environments/{id}

Update environment settings.

DELETE/environments/{id}

Delete an environment.

POST/environments/{id}/drift-check

Trigger a drift detection scan.

Response

{ "detail": "Drift check initiated", "environment_id": "uuid" }
POST/environments/{id}/drift-resolve

Mark drift as resolved.

Projects

Terraform projects mapped to repositories. Assign projects to instances via the graph API.

GET/projects

List all projects.

POST/projects

Create a Terraform project.

Request Body

{ "name": "vpc-core", "repository_url": "https://github.com/org/infra",
  "terraform_path": "modules/vpc", "workspace": "default",
  "branch": "main", "state_backend": "platform" }
PUT/projects/{id}

Update project settings.

DELETE/projects/{id}

Delete a project and its dependencies.

POST/projects/{id}/assign/{instance_id}

Assign a project to an Atlantis instance.

DELETE/projects/{id}/assign

Unassign project from its instance.

POST/projects/{id}/dependencies

Add a dependency between projects.

Request Body

{ "depends_on_project_id": "uuid", "output_mapping": {} }
DELETE/projects/{id}/dependencies/{dep_id}

Remove a project dependency.

GET/projects/graph

Get the full project/instance graph for visualization.

Response

{ "nodes": [{ "id": "...", "type": "project", "data": {...},
   "position": { "x": 0, "y": 0 } }],
  "edges": [{ "id": "...", "source": "...", "target": "...",
   "type": "assignment" }] }
POST/projects/graph/layout

Save graph node positions.

Request Body

[{ "id": "uuid", "position_x": 100, "position_y": 200 }]

Runs

Terraform plan, apply, and destroy operations. AI agents can create runs and approve applies programmatically.

GET/runs

List runs. Filter by status or environment.

Response

[{ "id": "uuid", "title": "Plan VPC", "status": "planning",
   "command": "plan", "resources_added": 2,
   "resources_changed": 0, "resources_destroyed": 0 }]
GET/runs/scheduled

List scheduled future runs.

POST/runs

Create and trigger a new run.

Request Body

{ "title": "Scale EKS nodes", "command": "apply",
  "repo": "org/infra", "branch": "main",
  "workspace": "production", "scheduled_at": "2026-03-20T10:00:00Z" }
GET/runs/{id}

Get run details including log output.

POST/runs/{id}/approve

Approve a planned run to proceed with apply.

POST/runs/{id}/cancel

Cancel a pending or planning run.

State Backend

Terraform HTTP state backend. Configure your projects to store encrypted state on Atlantas.

# backend.tf
terraform {
  backend "http" {
    address        = "https://api.atlantascloud.com/api/v1/tfstate/my-project/default"
    lock_address   = "https://api.atlantascloud.com/api/v1/tfstate/my-project/default"
    unlock_address = "https://api.atlantascloud.com/api/v1/tfstate/my-project/default"
    lock_method    = "LOCK"
    unlock_method  = "UNLOCK"
  }
}
GET/tfstate/{project}/{workspace}

Retrieve the current Terraform state (decrypted).

POST/tfstate/{project}/{workspace}

Store a new state version. Encrypted with AES-256 before storage.

LOCK/tfstate/{project}/{workspace}

Acquire a state lock. Returns 409 if already locked.

Request Body

{ "ID": "lock-uuid", "Operation": "OperationTypeApply",
  "Info": "", "Who": "user@host", "Version": "1.7.0",
  "Created": "2026-03-15T10:00:00Z", "Path": "" }
UNLOCK/tfstate/{project}/{workspace}

Release a state lock.

Request Body

{ "ID": "lock-uuid" }

State Management

UI-facing API for browsing states and version history.

GET/states

List all Terraform states in the tenant.

Response

[{ "id": "uuid", "project_name": "vpc-core", "workspace": "default",
   "serial": 4, "is_locked": false, "lineage": "..." }]
GET/states/{id}

Get state metadata.

GET/states/{id}/versions

List version history for a state.

POST/states/{id}/unlock

Force-unlock a stuck state.

DELETE/states/{id}

Delete a state and all its versions.

Agents

Autonomous operators that monitor, fix, and maintain infrastructure. Types: drift_monitor, state_watcher, apply_bot, upgrade_bot, codebase_monitor.

GET/agents

List all configured agents.

POST/agents

Create an agent.

Request Body

{ "name": "prod-drift-watcher", "agent_type": "drift_monitor",
  "schedule": "*/15 * * * *",
  "target_instance_id": "uuid",
  "config": { "auto_remediate": true } }
PUT/agents/{id}

Update agent settings.

DELETE/agents/{id}

Delete an agent.

POST/agents/{id}/activate

Activate an agent to run on its schedule.

POST/agents/{id}/deactivate

Pause an active agent.

POST/agents/{id}/trigger

Manually trigger an agent run outside its schedule.

GitHub Apps

Register GitHub Apps to browse repos, branches, and auto-discover Terraform workspaces.

GET/github/apps

List registered GitHub Apps.

POST/github/apps

Register a GitHub App. Private key is encrypted at rest.

Request Body

{ "name": "My Org App", "app_id": "12345",
  "installation_id": "67890", "account_login": "my-org",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----..." }
DELETE/github/apps/{id}

Remove a GitHub App registration.

GET/github/apps/{id}/repos

List accessible repositories.

GET/github/apps/{id}/repos/{owner}/{repo}/branches

List branches for a repository.

GET/github/apps/{id}/repos/{owner}/{repo}/tree

Get full directory tree. Query param: ref (default: main).

GET/github/apps/{id}/repos/{owner}/{repo}/terraform-workspaces

Auto-discover Terraform workspaces by scanning for .tf files.

Cloud Credentials

Encrypted storage for cloud provider credentials. Supports AWS, GCP, Azure, Hetzner, and DigitalOcean.

GET/cloud-credentials

List credentials. Secrets are never returned.

POST/cloud-credentials

Store new credentials. Encrypted with AES-256.

Request Body

{ "name": "AWS Production", "provider": "aws",
  "credential_type": "access_key",
  "credentials_json": { "access_key_id": "...", "secret_access_key": "..." } }
PUT/cloud-credentials/{id}

Update credential name or rotate secrets.

DELETE/cloud-credentials/{id}

Delete a credential.

POST/cloud-credentials/{id}/validate

Test that stored credentials are valid.

SSO Providers

Configure OIDC, SAML, Google, or GitHub SSO for your tenant.

GET/sso-providers

List configured SSO providers.

POST/sso-providers

Create an SSO provider.

Request Body

{ "name": "Corporate Okta", "provider_type": "oidc",
  "client_id": "...", "client_secret": "...",
  "issuer_url": "https://company.okta.com" }
PUT/sso-providers/{id}

Update SSO configuration.

DELETE/sso-providers/{id}

Remove an SSO provider.

POST/sso-providers/{id}/test

Test SSO provider connectivity.

Users & API Tokens

Manage team members and issue scoped API tokens for agents.

GET/users

List all users in the tenant.

PUT/users/{id}/role

Change a user's role.

Request Body

{ "role": "member" }
DELETE/users/{id}

Deactivate a user.

GET/users/tokens

List your API tokens.

POST/users/tokens

Generate a new API token. The raw token is only shown once.

Request Body

{ "name": "CI/CD Token", "expires_in_days": 90 }

Response

{ "id": "uuid", "name": "CI/CD Token", "raw_token": "atl_...",
  "expires_at": "2026-06-15T00:00:00Z" }
DELETE/users/tokens/{id}

Revoke an API token.

Tenant & Quotas

View and manage tenant-level settings and resource quotas.

GET/tenant

Get tenant info including quotas.

Response

{ "id": "uuid", "name": "Acme Corp", "slug": "acme",
  "max_instances": 10, "max_environments": 20,
  "cpu_quota": "4000m", "memory_quota": "8Gi" }
PUT/tenant/quotas

Update resource quotas.

Request Body

{ "max_instances": 20, "cpu_quota": "8000m" }
GET/tenant/usage

Get current resource usage vs limits.

Response

{ "instances_used": 3, "instances_limit": 10,
  "environments_used": 5, "environments_limit": 20 }

Billing

View billing records and export invoices.

GET/billing

List all billing records.

GET/billing/current

Get current month billing summary.

Response

{ "current_resources": 42, "current_changes": 156,
  "current_amount_cents": 2100,
  "period_start": "2026-03-01", "period_end": "2026-03-31" }
GET/billing/export

Download billing records as CSV.

Dashboard

Aggregated statistics for the tenant overview.

GET/dashboard/stats

Get dashboard statistics.

Response

{ "total_runs": 1247, "applied_runs": 1089,
  "errored_runs": 23, "pending_runs": 5,
  "active_instances": 4, "total_environments": 8,
  "success_rate": 87.3 }