Skip to main content

Live Resources

DriftWise stores the resources discovered during each cloud scan in a tenant-isolated inventory. The endpoints below let you browse that inventory, request on-demand property enrichment for a single resource, and check a high-level posture summary across every cloud account in your organization. For endpoint shapes, see the accounts tag (resources and enrichment) and the drift tag (posture summary) of the API reference.

All routes are org-scoped. Listing resources and getting a posture summary require org membership. Triggering enrichment requires the owner or admin role. Authentication accepts either an API key (dw2_ prefix) or an OIDC JWT via the Authorization: Bearer header.

Listing live resources​

GET /orgs/:id/resources returns a paginated list of the live resources in an organization, optionally filtered by cloud account via ?account_id=<uuid>. Default page size is 100, max is 500.

Response fields​

Each resource row carries:

  • provider_resource_id — the cloud-native identifier (AWS ARN, GCP self-link, Azure resource ID).
  • provider_type — the cloud-native type string (e.g. AWS::EC2::Instance, compute.googleapis.com/Instance, Microsoft.Compute/virtualMachines).
  • normalized_type — the broad DriftWise resource category used for filtering and risk classification.
  • iac_resource_id — populated when a resource has been matched to a declared IaC resource; omitted from the JSON response otherwise.
  • enrichment_status — see Cloud Discovery for the full list of values.
  • last_seen_at — timestamp of the most recent scan that observed this resource.

Enriching a resource​

POST /orgs/:id/resources/:resource_id/enrich triggers on-demand property fetching for a single resource. Use this when enrichment_status is none or failed and you want fresh properties without waiting for the next scheduled scan.

No request body. The response is the same shape as a list entry plus a properties object (the raw, redacted cloud provider payload) and an enrichment_failure_reason field.

Behavior by provider​

  • AWS — calls CloudControl GetResource and stores the resulting property blob after pattern-based scrubbing.
  • GCP and Azure — the discovery APIs already return full properties, so there is no separate enricher. The endpoint force-transitions the resource to enrichment_status = n/a and returns the current row. This is a safe no-op you can call to reconcile a resource that was stuck in failed against a non-enriching provider.

Status codes​

StatusWhen
200 OKEnrichment succeeded, or the resource was already enriched / n/a.
403 ForbiddenCaller lacks the owner or admin role required to trigger enrichment.
404 Not FoundResource or cloud account not found in this org.
422 Unprocessable EntityEnricher reported a per-resource failure (permission denied, resource gone). The row is marked failed and the reason is returned.
500 Internal Server ErrorDatabase, credential, or enrichment-pipeline failure that is not attributable to the single resource.
503 Service UnavailableCloud registry is not configured on the server.

Getting a posture summary​

GET /orgs/:id/posture returns a one-row-per-cloud-account summary of IaC coverage and undeclared resources. Useful for dashboard widgets and CI gates that need a single-call overview of an org's posture without fetching every resource.

Response fields​

  • coverage_pct — the percentage of live resources that are matched to a declared IaC resource. Omitted from the response until the account has been scanned at least once.
  • risk_level — one of critical, high, medium, low, or none, derived from the drift-change risk flags on the latest snapshot (e.g. destroying a stateful resource → critical, replacement-causing-downtime → high, security-group change → medium). Omitted until the account has a drift snapshot.
  • undeclared_count — counts live resources with no matching IaC resource — a rough proxy for drift-by-omission. Independent of risk_level.

Accounts are returned ordered by coverage_pct ascending (lowest coverage first), with unscanned accounts (coverage_pct absent) last. Consumers should still key by cloud_account_id rather than position.

Endpoint reference​

Resource listing and enrichment live under the accounts tag of the API reference. The posture summary lives under the drift tag alongside drift results. Scan lifecycle endpoints are under scans.