trueno
Docs · API reference

The truenoREST API.

Read-only access to your findings, recommendations, resources, and accounts. Bearer-key auth, org-scoped, JSON. Machine-readable OpenAPI 3.1 at /api/v1/openapi.json.

01 · Authentication

Bearer API key.

Create a key under Settings → Integrations (Control & Enterprise). It's shown once — store it securely. Send it on every request.

curl -H "Authorization: Bearer trn_live_…" \
  "https://trueno.io/api/v1/findings?status=open"

Base URL: https://trueno.io/api/v1. All responses are { "data": [ … ] }. Unknown or revoked keys return 401. Requests are scoped to the key's organization.

02 · Endpoints

Four read endpoints.

Each returns a data array of the linked schema. Pass ?limit (1–500, default 100) on any of them.

GET/api/v1/findings

List findings. Returns { data: Finding[] }.

Query parameters
  • status · optional — Comma-separated: open, ignored, resolved. Defaults to open. e.g. open,resolved
  • severity · optional — Comma-separated: critical, high, medium, low. e.g. critical,high
  • limit · optional — Max rows (1–500, default 100). e.g. 100
GET/api/v1/recommendations

List open recommendations, ranked by priority score. Returns { data: Recommendation[] }.

Query parameters
  • limit · optional — Max rows (1–500, default 100). e.g. 100
GET/api/v1/resources

List cloud resources. Returns { data: Resource[] }.

Query parameters
  • service · optional — Comma-separated service slugs. e.g. s3,ec2
  • awsAccountId · optional — Filter to one connected account (trueno account id, a UUID).
  • limit · optional — Max rows (1–500, default 100). e.g. 100
GET/api/v1/accounts

List connected AWS accounts. Returns { data: Account[] }.

03 · Schemas

Response objects.

The shape of each object inside the data array.

Finding

A detected issue against an AWS resource.

  • id string
  • title string
  • severity stringcritical | high | medium | low
  • status stringopen | ignored | resolved
  • category string
  • awsAccountId string
  • resourceId string
  • resourceType string
  • region string | null
  • estimatedMonthlySavings number | null
  • detectedAt string (date-time)
  • updatedAt string (date-time)

Recommendation

A recommended action, carrying the unified priority score (#32).

  • id string
  • title string
  • category string
  • status string
  • priority string
  • impact string
  • effort string
  • confidence number
  • priorityScore numberUnified 0–100 ranking score; results are sorted by this descending.
  • estimatedMonthlySavings number | null
  • estimatedRiskReduction number | null
  • recommendation string
  • createdAt string (date-time)

Resource

A discovered cloud resource.

  • id string
  • accountId string12-digit AWS account id.
  • service string
  • resourceType string
  • resourceId string
  • arn string | null
  • name string | null
  • region string | null
  • status string
  • riskScore number | null
  • costScore number | null
  • tags object<string,string>
  • discoveredAt string (date-time)
  • lastSeenAt string (date-time)

Account

A connected AWS account with scan freshness + rolled-up metrics.

  • id string
  • accountId string12-digit AWS account id.
  • name string
  • environment string
  • status string
  • isManagement boolean
  • lastScanAt string | null (date-time)
  • lastScanState string | null
  • connectedAt string | null (date-time)
  • openFindingsCount number | null
  • estimatedMonthlySpend number | null
04 · Webhooks

Signed outbound events.

Add an endpoint under Settings → Integrations → Webhooks and subscribe to events. trueno POSTs a signed JSON envelope when one fires.

  • critical_finding — A new critical-severity finding was detected.
  • cost_anomaly — Spend spiked above the recent baseline.
  • security_drift — A guarded security control regressed from a known-good state (e.g. encryption or Block Public Access disabled).
X-Trueno-Event: critical_finding
X-Trueno-Delivery: <delivery-id>
X-Trueno-Signature: sha256=<hmac>

{ "event": "critical_finding", "createdAt": "…", "organizationId": "…", "data": { … } }

Verify X-Trueno-Signatureas an HMAC-SHA256 of the raw request body keyed by your endpoint's signing secret before trusting the payload. Non-2xx responses and timeouts are retried automatically with exponential backoff; every attempt is logged under Recent deliveries.

05 · OpenAPI

Machine-readable spec.

Generate clients or import into Postman/Insomnia/Bruno from the OpenAPI 3.1 document.

curl https://trueno.io/api/v1/openapi.json

Need a key or hitting a 401?

API keys + webhooks are managed by org admins under Settings → Integrations on Control and Enterprise. Open support with your workspace id if a key won't authenticate.
Open IntegrationsIntegration setup guide