Nodes API

Nodes are the fundamental building blocks of Infracast's infrastructure graph. Each node represents a single resource — an EC2 instance, S3 bucket, IAM user, RDS database, security group, Kubernetes pod, or any other discovered resource. Nodes have a type, properties, and connect to other nodes via edges.

---

Endpoints

Method	Path	Description	Permission
GET	/api/v1/tenants/{tenantID}/nodes	List nodes with filters	nodes:read
GET	/api/v1/tenants/{tenantID}/nodes/{nodeID}	Get a single node	nodes:read
POST	/api/v1/tenants/{tenantID}/nodes	Create a node	jobs:create
POST	/api/v1/tenants/{tenantID}/nodes/query	Bulk query nodes	nodes:read
GET	/api/v1/tenants/{tenantID}/nodes/{nodeID}/neighbors	Get connected nodes	nodes:read
GET	/api/v1/tenants/{tenantID}/graph/summary	Graph statistics	nodes:read

---

List Nodes

GET /api/v1/tenants/{tenantID}/nodes

Returns a paginated list of nodes in the tenant's infrastructure graph.

Query Parameters

Parameter	Type	Description
types	string	Comma-separated node types to filter (e.g., aws.ec2.instance,aws.rds.db_instance)
region	string	AWS/Azure/GCP region (e.g., us-east-1)
account_id	string	Cloud account/subscription ID
search	string	Fuzzy search on node name or ID
tags	string	Filter by tag key=value pairs (e.g., Environment=prod)
page	int	Page number (default: 1)
per_page	int	Results per page (default: 50, max: 500)
sort	string	Sort field. Prefix with - for descending (e.g., -created_at)

Example Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.infracast.io/api/v1/tenants/acme-corp/nodes?types=aws.ec2.instance&region=us-east-1&per_page=25"

Example Response

{
  "items": [
    {
      "id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
      "type": "aws.ec2.instance",
      "name": "prod-web-01",
      "account_id": "123456789012",
      "region": "us-east-1",
      "properties": {
        "InstanceType": "t3.medium",
        "State": "running",
        "PrivateIpAddress": "10.0.1.45",
        "PublicIpAddress": "54.201.23.45",
        "ImageId": "ami-0123456789abcdef0",
        "SubnetId": "subnet-0abc123",
        "VpcId": "vpc-0def456",
        "IamInstanceProfile": "arn:aws:iam::123456789012:instance-profile/WebServerRole",
        "EbsOptimized": "true",
        "MonitoringState": "enabled",
        "Tags": "{\"Environment\":\"prod\",\"Team\":\"platform\"}"
      },
      "tags": {
        "Environment": "prod",
        "Team": "platform"
      },
      "discovered_at": "2024-03-16T08:30:00Z",
      "updated_at": "2024-03-16T08:30:00Z"
    },
    {
      "id": "aws:us-east-1:aws.ec2.instance:i-0bcd234ef567890b",
      "type": "aws.ec2.instance",
      "name": "prod-web-02",
      "account_id": "123456789012",
      "region": "us-east-1",
      "properties": {
        "InstanceType": "t3.medium",
        "State": "running",
        "PrivateIpAddress": "10.0.1.67"
      },
      "discovered_at": "2024-03-16T08:30:00Z",
      "updated_at": "2024-03-16T08:30:00Z"
    }
  ],
  "total": 847,
  "page": 1,
  "per_page": 25,
  "total_pages": 34
}

---

Get a Node

GET /api/v1/tenants/{tenantID}/nodes/{nodeID}

Returns full details for a single node including all properties.

Example Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.infracast.io/api/v1/tenants/acme-corp/nodes/aws:us-east-1:aws.ec2.instance:i-0abc123def456789a"

Example Response

{
  "id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
  "type": "aws.ec2.instance",
  "name": "prod-web-01",
  "account_id": "123456789012",
  "region": "us-east-1",
  "properties": {
    "InstanceType": "t3.medium",
    "State": "running",
    "PrivateIpAddress": "10.0.1.45",
    "PublicIpAddress": "54.201.23.45",
    "ImageId": "ami-0123456789abcdef0",
    "SubnetId": "subnet-0abc123",
    "VpcId": "vpc-0def456",
    "IamInstanceProfile": "arn:aws:iam::123456789012:instance-profile/WebServerRole",
    "EbsOptimized": "true",
    "MonitoringState": "enabled",
    "SecurityGroups": "[\"sg-0abc123\",\"sg-0def456\"]",
    "KeyName": "prod-keypair",
    "Architecture": "x86_64",
    "Tags": "{\"Environment\":\"prod\",\"Team\":\"platform\",\"Project\":\"infracast\"}"
  },
  "tags": {
    "Environment": "prod",
    "Team": "platform",
    "Project": "infracast"
  },
  "discovered_at": "2024-03-16T08:30:00Z",
  "updated_at": "2024-03-16T08:30:00Z"
}

---

Node Types

Infracast discovers and represents a wide range of resource types:

AWS

Type	Description
aws.ec2.instance	EC2 compute instances
aws.ec2.security_group	VPC security groups
aws.ec2.subnet	VPC subnets
aws.ec2.vpc	Virtual Private Clouds
aws.rds.db_instance	RDS database instances
aws.s3.bucket	S3 storage buckets
aws.iam.user	IAM users
aws.iam.role	IAM roles
aws.iam.policy	IAM managed policies
aws.elbv2.load_balancer	Application/Network Load Balancers
aws.lambda.function	Lambda functions
aws.eks.cluster	EKS Kubernetes clusters
aws.cloudtrail.trail	CloudTrail trails
aws.kms.key	KMS encryption keys
aws.shield.subscription	AWS Shield subscription

Azure

Type	Description
azure.compute.virtual_machine	Azure VMs
azure.network.network_security_group	NSGs
azure.storage.storage_account	Storage accounts
azure.sql.server	Azure SQL servers
azure.keyvault.vault	Key Vault instances

GCP

Type	Description
gcp.compute.instance	GCE instances
gcp.compute.firewall	VPC firewall rules
gcp.storage.bucket	Cloud Storage buckets
gcp.sql.instance	Cloud SQL instances

Kubernetes

Type	Description
k8s.pod	Pods
k8s.service	Services
k8s.namespace	Namespaces
k8s.deployment	Deployments
k8s.clusterrole	RBAC ClusterRoles

---

Get Node Neighbors

Retrieve all nodes connected to a given node in the graph:

GET /api/v1/tenants/{tenantID}/nodes/{nodeID}/neighbors

# Optional: filter by edge type
GET /api/v1/tenants/{tenantID}/nodes/{nodeID}/neighbors?edge_type=ATTACHED_TO

{
  "node_id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
  "neighbors": [
    {
      "node": {
        "id": "aws:us-east-1:aws.ec2.security_group:sg-0abc123",
        "type": "aws.ec2.security_group",
        "name": "web-servers-sg"
      },
      "edge_type": "MEMBER_OF",
      "direction": "outbound"
    },
    {
      "node": {
        "id": "aws:us-east-1:aws.elbv2.load_balancer:arn:aws:elasticloadbalancing:...",
        "type": "aws.elbv2.load_balancer",
        "name": "prod-alb"
      },
      "edge_type": "ROUTES_TO",
      "direction": "inbound"
    }
  ]
}

---

Bulk Query

For large-scale queries, use the bulk query endpoint:

POST /api/v1/tenants/{tenantID}/nodes/query
{
  "types": ["aws.s3.bucket"],
  "filters": {
    "properties": {
      "PublicAccessBlockEnabled": "false"
    }
  },
  "limit": 100
}

---

Graph Summary

Get aggregate statistics about your infrastructure graph:

GET /api/v1/tenants/{tenantID}/graph/summary

{
  "total_nodes": 5420,
  "total_edges": 18340,
  "by_type": {
    "aws.ec2.instance": 342,
    "aws.ec2.security_group": 89,
    "aws.s3.bucket": 67,
    "aws.iam.user": 234,
    "aws.iam.role": 512,
    "aws.rds.db_instance": 28
  },
  "by_region": {
    "us-east-1": 3120,
    "us-west-2": 1840,
    "eu-west-1": 460
  },
  "last_discovered": "2024-03-16T08:30:00Z"
}

---

Python Example

from infracast import InfracastClient

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

# List all EC2 instances in us-east-1
instances = client.nodes.list(
    tenant="acme-corp",
    types=["aws.ec2.instance"],
    region="us-east-1"
)

for node in instances:
    state = node.properties.get("State", "unknown")
    instance_type = node.properties.get("InstanceType", "unknown")
    print(f"{node.name}: {instance_type} ({state})")

# Get a specific node
node = client.nodes.get(tenant="acme-corp", node_id="aws:us-east-1:aws.ec2.instance:i-0abc123")
print(f"VPC: {node.properties['VpcId']}")

---

Next Steps

• Edges API — Explore relationships between nodes
• Findings API — Compliance findings for nodes
• Discovery Jobs API — Run discovery to populate nodes