Discovery Endpoint

The discovery endpoint is the core of the LightPane API. It accepts a batch of service requests and returns structured data for each.

Request

POST /discovery
Content-Type: application/json
Authorization: Bearer csl_ak_YOUR_KEY_HERE

Request body

{
    "services": [
        {
            "service": "ec2",
            "provider": "aws",
            "region": "eu-west-2",
            "attributes": ["name", "instance_id", "instance_type", "state", "private_ip"]
        }
    ]
}

Service request fields

Field	Type	Required	Description
service	string	Yes	Service identifier. See the Service Catalogue.
provider	string	Yes	aws, gcp, or azure.
region	string	Yes	Cloud region (e.g., eu-west-2, europe-west2).
attributes	array	No	Attribute names to return. Omit for all attributes.
account	string	No	Account alias (for account group keys). Overrides provider and region.

Batch requests

Send multiple services in a single call. The API discovers all services in parallel and returns results for each:

{
    "services": [
        {
            "service": "ec2",
            "provider": "aws",
            "region": "eu-west-2",
            "attributes": ["name", "instance_id", "state"]
        },
        {
            "service": "s3",
            "provider": "aws",
            "region": "eu-west-2",
            "attributes": ["bucket_name", "region", "versioning_status"]
        },
        {
            "service": "lambda_functions",
            "provider": "aws",
            "region": "eu-west-2",
            "attributes": ["function_name", "runtime", "memory_size"]
        },
        {
            "service": "gcp_compute_instances",
            "provider": "gcp",
            "region": "europe-west2",
            "attributes": ["name", "machine_type", "status", "zone"]
        }
    ]
}

Batch size limits

Access keys may have a max_batch_size constraint limiting the number of services per request. If exceeded, the API returns 400 Bad Request.

Response

Successful response

{
    "results": [
        {
            "metadata": {
                "service": "ec2",
                "service_label": "EC2 Instances",
                "provider": "aws",
                "region": "eu-west-2",
                "count": 2,
                "timestamp": "2026-03-28T14:30:00Z"
            },
            "columns": [
                { "key": "name", "label": "Name" },
                { "key": "instance_id", "label": "Instance ID" },
                { "key": "state", "label": "State" }
            ],
            "rows": [
                {
                    "name": "web-server-1",
                    "instance_id": "i-0abc123def456789",
                    "state": "running"
                },
                {
                    "name": "worker-1",
                    "instance_id": "i-0def456abc789012",
                    "state": "stopped"
                }
            ]
        }
    ]
}

Response fields

Top level:

Field	Type	Description
results	array	One entry per service request, in the same order as the request.

Per result:

Field	Type	Description
metadata.service	string	Service identifier
metadata.service_label	string	Human-readable service name
metadata.provider	string	Cloud provider
metadata.region	string	Region queried
metadata.count	number	Number of resources found
metadata.timestamp	string	ISO 8601 timestamp of the discovery
columns	array	Column definitions with key and label
rows	array	Resource data, one object per resource

Partial failure

If some services succeed and others fail, the response includes both. Failed services have a success: false field and an error message instead of columns and rows:

{
    "results": [
        {
            "metadata": { "service": "ec2", "provider": "aws", "region": "eu-west-2" },
            "columns": [...],
            "rows": [...]
        },
        {
            "service": "rds_instances",
            "success": false,
            "error": "Service rds_instances not permitted by this token"
        }
    ]
}

Examples

Discover EC2 instances

curl -X POST https://api.lightpane.cloud/discovery \
  -H "Authorization: Bearer csl_ak_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "services": [{
      "service": "ec2",
      "provider": "aws",
      "region": "eu-west-2",
      "attributes": ["name", "instance_id", "instance_type", "state", "launch_time"]
    }]
  }'

Discover across providers

curl -X POST https://api.lightpane.cloud/discovery \
  -H "Authorization: Bearer csl_ak_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "services": [
      {
        "service": "ec2",
        "provider": "aws",
        "region": "eu-west-2"
      },
      {
        "service": "gcp_compute_instances",
        "provider": "gcp",
        "region": "europe-west2"
      }
    ]
  }'

Using account aliases

curl -X POST https://api.lightpane.cloud/discovery \
  -H "Authorization: Bearer csl_ak_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "services": [
      { "service": "ec2", "account": "prod-aws" },
      { "service": "gcp_compute_instances", "account": "prod-gcp" },
      { "service": "ec2", "account": "staging-aws" }
    ]
  }'