Skip to main content

API Overview

Infracast provides a comprehensive REST API for programmatic access to all platform features.

Base URL​

EnvironmentURL
Productionhttps://api.infracast.io
Developmenthttps://dev.infracast.io
Self-hostedhttps://your-domain.com

Authentication​

All API requests require a Bearer token:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.infracast.io/api/v1/tenants/my-tenant/nodes

See Authentication for details on obtaining tokens.

API Versioning​

The API is versioned via URL path:

/api/v1/...   # Current stable version

Breaking changes will increment the version. Deprecation notices are provided 6 months before removal.

Common Patterns​

Request Format​

  • Content-Type: application/json
  • Method: GET (read), POST (create), PUT (update), DELETE (remove)

Response Format​

All responses follow a consistent structure:

{
  "data": { ... },          // Response payload
  "meta": {                 // Metadata (optional)
    "total": 142,
    "page": 1,
    "per_page": 50
  },
  "error": null             // Error details (if any)
}

Error Responses​

Errors include a code and message:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": null
  }
}
HTTP StatusError CodeDescription
400BAD_REQUESTInvalid request body or parameters
401UNAUTHORIZEDMissing or invalid token
403FORBIDDENInsufficient permissions
404NOT_FOUNDResource doesn't exist
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Pagination​

List endpoints support pagination:

# Get page 2 with 100 items per page
GET /api/v1/tenants/{tenant}/nodes?page=2&per_page=100

Response includes pagination metadata:

{
  "items": [...],
  "total": 5420,
  "page": 2,
  "per_page": 100,
  "total_pages": 55
}

Filtering​

Most list endpoints support filtering:

# Filter nodes by type and region
GET /api/v1/tenants/{tenant}/nodes?types=aws.ec2.instance&region=us-east-1

# Filter findings by severity
GET /api/v1/tenants/{tenant}/findings?severity=HIGH,CRITICAL

Sorting​

Sort results using sort parameter:

# Sort by created_at descending
GET /api/v1/tenants/{tenant}/nodes?sort=-created_at

# Sort by name ascending
GET /api/v1/tenants/{tenant}/nodes?sort=name

Rate Limiting​

PlanRequests/minuteBurst
Free6010
Pro30050
Enterprise1000100

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1710432000

When rate limited, you'll receive:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Quick Reference​

Health & Status​

EndpointMethodDescription
/healthzGETHealth check (no auth)
/api/v1/statusGETAPI status with DB connection

Authentication​

EndpointMethodDescription
/api/v1/auth/tokenPOSTGet access token
/api/v1/auth/refreshPOSTRefresh expired token
/api/v1/auth/meGETCurrent user info

Tenants​

EndpointMethodDescription
/api/v1/tenantsGETList tenants
/api/v1/tenantsPOSTCreate tenant
/api/v1/tenants/{id}GETGet tenant
/api/v1/tenants/{id}PUTUpdate tenant
/api/v1/tenants/{id}DELETEDelete tenant

Nodes​

EndpointMethodDescription
/api/v1/tenants/{t}/nodesGETList nodes
/api/v1/tenants/{t}/nodes/{id}GETGet node
/api/v1/tenants/{t}/nodesPOSTCreate node
/api/v1/tenants/{t}/nodes/{id}DELETEDelete node

Edges​

EndpointMethodDescription
/api/v1/tenants/{t}/edgesGETList edges
/api/v1/tenants/{t}/edgesPOSTCreate edge
/api/v1/tenants/{t}/edges/{id}DELETEDelete edge

Findings​

EndpointMethodDescription
/api/v1/tenants/{t}/findingsGETList findings
/api/v1/tenants/{t}/findings/{id}GETGet finding
/api/v1/tenants/{t}/findings/{id}/acceptPOSTAccept risk
/api/v1/tenants/{t}/findings/{id}/resolvePOSTMark resolved

Discovery Jobs​

EndpointMethodDescription
/api/v1/tenants/{t}/jobsGETList jobs
/api/v1/tenants/{t}/jobsPOSTCreate job
/api/v1/tenants/{t}/jobs/{id}GETGet job
/api/v1/tenants/{t}/jobs/{id}/startPOSTStart job
/api/v1/tenants/{t}/jobs/{id}/cancelPOSTCancel job

Compliance​

EndpointMethodDescription
/api/v1/tenants/{t}/compliance/summaryGETCompliance overview
/api/v1/tenants/{t}/compliance/frameworksGETFramework scores
/api/v1/tenants/{t}/compliance/controlsGETControl status

Reports​

EndpointMethodDescription
/api/v1/tenants/{t}/reportsGETList reports
/api/v1/tenants/{t}/reports/generatePOSTGenerate report
/api/v1/tenants/{t}/reports/{id}/downloadGETDownload report

Path Tracer​

EndpointMethodDescription
/api/v1/tenants/{t}/pathtracer/tracePOSTTrace network path

SDKs & Libraries​

Official SDKs​

  • Python: pip install infracast (PyPI)
  • Go: go get github.com/azgardtek/infracast-go
  • JavaScript/TypeScript: npm install @infracast/sdk

Example: Python SDK​

from infracast import InfracastClient

client = InfracastClient(
    api_url="https://api.infracast.io",
    api_token="your-token"
)

# List nodes
nodes = client.nodes.list(
    tenant="my-tenant",
    types=["aws.ec2.instance"],
    region="us-east-1"
)

# Get compliance summary
summary = client.compliance.summary(tenant="my-tenant")
print(f"Overall score: {summary.score}%")

# Trace path
result = client.pathtracer.trace(
    tenant="my-tenant",
    source_node_id="aws:us-east-1:aws.ec2.instance:web-01",
    destination_cidr="0.0.0.0/0",
    port=443,
    protocol="tcp"
)
print(f"Reachable: {result.reachable}")

OpenAPI Specification​

The full OpenAPI 3.0 spec is available at:

https://api.infracast.io/api/v1/openapi.yaml

Import into Postman, Insomnia, or your favorite API tool.

Webhooks​

Configure webhooks to receive real-time notifications:

POST /api/v1/tenants/{tenant}/webhooks
{
  "url": "https://your-app.com/infracast-webhook",
  "events": ["finding.created", "job.completed"],
  "secret": "your-webhook-secret"
}

See Webhooks for event types and payload formats.