Guardrails API Pro+

Manage infrastructure policy guardrails that evaluate Terraform plans before they are applied.

Endpoints Summary

Method	Endpoint	Description
GET	/api/guardrails	List all guardrails
POST	/api/guardrails	Create a guardrail
GET	/api/guardrails/:id	Get guardrail details
PATCH	/api/guardrails/:id	Update a guardrail
DELETE	/api/guardrails/:id	Delete a guardrail
POST	/api/guardrails/:id/deploy	Deploy to repositories
POST	/api/guardrails/:id/undeploy	Remove from repositories
GET	/api/guardrails/templates	List guardrail templates

Authentication

All endpoints require a Bearer token in the Authorization header.

Authorization: Bearer <your-api-token>

---

List Guardrails

GET /api/guardrails

Returns all guardrails for the current organization.

Query Parameters:

Parameter	Type	Description
status	string	Filter: active, inactive
enforcement	string	Filter by mode: block, warn, dry_run, require_approval
page	number	Page number (default: 1)
limit	number	Items per page (default: 20)

Example:

curl -X GET "https://api.controlinfra.com/api/guardrails?enforcement=block" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "guardrails": [
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "name": "No Public S3 Buckets",
      "description": "Prevent S3 buckets with public access",
      "enforcement": "block",
      "rules": [
        {
          "resourceType": "aws_s3_bucket",
          "attribute": "acl",
          "operator": "equals",
          "value": "public-read"
        }
      ],
      "deployedTo": ["663f1a2b...", "663f1a2c..."],
      "evaluationCount": 45,
      "violationCount": 3,
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 8,
  "page": 1,
  "pages": 1
}

---

Create a Guardrail

POST /api/guardrails

Request Body:

Field	Type	Required	Description
name	string	Yes	Guardrail name
description	string	No	Description
enforcement	string	Yes	block, warn, dry_run, or require_approval
rules	array	Yes	One or more policy rules
rules[].resourceType	string	Yes	Terraform resource type (e.g., aws_s3_bucket)
rules[].attribute	string	Yes	Attribute to evaluate
rules[].operator	string	Yes	Comparison operator
rules[].value	any	No	Value to compare against (not needed for exists/not_exists)

Example:

curl -X POST "https://api.controlinfra.com/api/guardrails" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enforce Encryption at Rest",
    "description": "All RDS instances must have storage encryption enabled",
    "enforcement": "block",
    "rules": [
      {
        "resourceType": "aws_db_instance",
        "attribute": "storage_encrypted",
        "operator": "equals",
        "value": false
      }
    ]
  }'

Response: 201 Created

{
  "_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "name": "Enforce Encryption at Rest",
  "enforcement": "block",
  "rules": [...],
  "deployedTo": [],
  "createdAt": "2025-01-15T10:00:00Z"
}

---

Get Guardrail Details

GET /api/guardrails/:id

Returns full details including evaluation history.

Example:

curl -X GET "https://api.controlinfra.com/api/guardrails/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Update a Guardrail

PATCH /api/guardrails/:id

Update guardrail properties. Only provided fields are updated.

Example:

curl -X PATCH "https://api.controlinfra.com/api/guardrails/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement": "warn",
    "description": "Updated: warn instead of block"
  }'

---

Delete a Guardrail

DELETE /api/guardrails/:id

Deletes the guardrail and removes it from all deployed repositories.

Example:

curl -X DELETE "https://api.controlinfra.com/api/guardrails/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

---

Deploy Guardrail

POST /api/guardrails/:id/deploy

Deploy a guardrail to one or more repositories.

Request Body:

Field	Type	Required	Description
repositoryIds	string[]	Yes	Repository IDs to deploy to

Example:

curl -X POST "https://api.controlinfra.com/api/guardrails/665a1b2c.../deploy" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryIds": ["663f1a2b...", "663f1a2c..."]
  }'

Response:

{
  "message": "Guardrail deployed to 2 repositories",
  "deployedTo": ["663f1a2b...", "663f1a2c..."]
}

---

Undeploy Guardrail

POST /api/guardrails/:id/undeploy

Remove a guardrail from repositories.

Request Body:

Field	Type	Required	Description
repositoryIds	string[]	Yes	Repository IDs to remove from

Example:

curl -X POST "https://api.controlinfra.com/api/guardrails/665a1b2c.../undeploy" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryIds": ["663f1a2b..."]
  }'

---

List Templates

GET /api/guardrails/templates

Returns built-in guardrail templates.

Example:

curl -X GET "https://api.controlinfra.com/api/guardrails/templates" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "templates": [
    {
      "_id": "tpl_no_public_s3",
      "name": "No Public S3 Buckets",
      "description": "Block S3 buckets with public ACLs or public access",
      "category": "security",
      "rules": [
        {
          "resourceType": "aws_s3_bucket",
          "attribute": "acl",
          "operator": "equals",
          "value": "public-read"
        }
      ]
    },
    {
      "_id": "tpl_enforce_encryption",
      "name": "Enforce Encryption",
      "description": "Require encryption on RDS, S3, EBS, and EFS",
      "category": "security",
      "rules": [...]
    }
  ]
}

TIP

Use templates as a starting point. Create a guardrail from a template by copying its rules into a POST /api/guardrails request and customizing as needed.