📡

API Reference

Overview

The EchelonGraph REST API lets you integrate cloud security intelligence into your workflows, CI/CD pipelines, and existing tools. All endpoints are documented in our OpenAPI specification, available to customers upon request.

Authentication

All API requests require a valid bearer token. Authenticate via the login endpoint to receive an access token and refresh token pair. If MFA is enabled on your account, a second verification step is required.

Rate Limits

Two limits apply to every /api/v1 request, and the tighter one is the one you meet. A few endpoints add a stricter limit of their own on top (sign-up requests, for one).

Sustained: a per-caller ceiling enforced by our WAF. It counts every request you make as one caller (defined under Burst below) to the API in a 60-second window that starts with your first request — all paths together, across every serving instance — and refuses a request once that count passes the ceiling for the path it is on. Refused requests count too.

  • 12,000 requests per minute on /api/v1/public/cves and every path under it (200 per second sustained)
  • 6,000 requests per minute on /api/v1/public/vendor-advisories, /api/v1/public/cwes, /api/v1/public/ecosystems, /api/v1/public/vendors, /api/v1/public/shadow-ai-radar and /api/v1/public/kev/recent (100 per second sustained)
  • 60,000 requests per minute on /api/v1/health (1,000 per second sustained)
  • 300 requests per minute on /api/v1/ws, the WebSocket upgrade (5 per second sustained)
  • 120 requests per minute on /api/v1/signup-requests (2 per second sustained)
  • 600 requests per minute on any other /api/v1 path, every authenticated endpoint on this page included (10 per second sustained)

Because the count is shared, a heavy run on one path uses up the lower ceilings: after 600 requests in one window, any other /api/v1 path refuses you too, even if every one of those requests went to /api/v1/public/cves.

Burst: a per-caller limit on each serving instance. On top of that ceiling, the API enforces 500 requests/second per caller across the /api/v1 surface, counted by each serving instance, so it bounds a burst rather than your sustained rate. For both limits, one caller is one client address as our platform records it when your request arrives — an IPv4 address, or for IPv6 the /64 network the address belongs to — and not a value you can set in a header, so traffic from other callers does not spend your allowance. Clients that reach us from one shared IPv4 address or from one IPv6 /64 (an office NAT, a proxy relaying requests for others, or a hosting provider that puts several customers in one /64) share that one allowance. A host that rotates its IPv6 privacy addresses stays one caller, and a client that moves to a different IPv4 address or a different /64 starts a new one. One exception: a request that reaches the API from inside Google Cloud without a public address (for example, from a VM with no external IP, using Private Google Access) arrives with no client address our platform records, so every such caller is counted as the same caller and all of them share one per-second allowance, and one allowance under any endpoint's own stricter limit. Cloud NAT does not change this; to get an allowance of your own, give the workload an external IP address. Trusted first-party callers are exempt from both limits.

What you see. An admitted response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window: 1s and X-RateLimit-Reset for the per-second limit only, and the X-RateLimit-Remaining you read describes the instance that answered. The WAF's per-minute count is not shown until it refuses you. Over either limit you receive 429 Too Many Requests with Retry-After in seconds. A WAF refusal carries X-RateLimit-Window: 60s, X-RateLimit-Limit set to that path's per-minute ceiling, and a JSON body whose code is RATE_LIMIT_EXCEEDED; a refusal by the per-second limit carries X-RateLimit-Window: 1s.

Pagination

List endpoints support pagination via limit with offset (or a keyset cursor); some endpoints also accept page/page_size. Responses include a total count for easy navigation.

Key Capabilities

Cloud Assets

Query your complete cloud asset inventory across all connected providers. Filter by asset type, region, and risk score. Register and manage cloud account connections.

Blast Radius & Attack Graph

Retrieve the interactive attack surface graph — nodes, links, and traversal paths. Specify depth to compute the tenant's blast-radius attack graph.

Vulnerabilities & CVEs

Access your CVE feed with severity and status filtering. View remediation recommendations with priority rankings and track remediation workflow progress.

Alerts & Detection

List and manage security alerts by severity and status. Alerts are generated from open findings across your environment.

Compliance & Reports

Retrieve compliance scores per framework. Generate reports (executive, compliance, scan, alert, asset inventory) in CSV or JSON format with configurable date ranges.

Risk Scoring

Access risk score breakdowns by category — vulnerabilities (CVEs), misconfigurations, compliance, blast radius, and SLA breaches — for a unified view of your security posture.

Real-Time Events

EchelonGraph supports real-time event delivery via WebSocket connections, pushing updates as they happen:

  • Asset discovery
  • Vulnerability detections
  • Breach alerts
  • Compliance drift
  • System notices

Webhooks

Register webhook endpoints to receive event notifications at your own URLs. All webhook payloads are signed with HMAC-SHA256 for verification, ensuring payload integrity.

Supported events include critical and high alerts, CVE matches, scan completion, compliance drift, asset discovery, finding creation, and report readiness.

User Provisioning (SCIM 2.0)

Automate user lifecycle management directly from your identity provider. EchelonGraph's SCIM 2.0 integration supports user listing, creation, and group synchronization with any SCIM-compliant IdP.

Audit Trail

Query the immutable audit log to review every authentication event, permission change, data export, and configuration modification — with full filtering by action type, user, and date range.

Previous← Getting StartedNextArchitecture →