Findings API
Interactive Swagger UI — click Authorize to try requests with your access key, or with an OAuth client ID/secret (see Getting API Credentials for how to generate either).
See Recent Changes for what's changed in the last 6 months.
Overview
The Findings API provides access to security findings generated by eSentire Atlas: query, create, and update findings, inspect their evidence/activity history, and look up the service-desk case comments/emails for a finding that was escalated.
Base URL: https://api.esentire.com/finding
Finding lifecycle: Draft → Open → Resolved → Closed (a finding can also be reopened back to Open). Classification: severity (Info/Low/Medium/High/Critical) × category (Attack/Vulnerability/Suspicious/Benign).
v1 vs v2: GET /v2/findings, GET /v2/findings/{finding_id}, POST /v2/findings and PATCH /v2/findings/{finding_id} are the current way to list/read/create/update findings, returning consistent lower_snake_case field names. Older GET /findings, GET /findings/{finding_id}, POST /findings and PATCH /findings/{finding_id}/update endpoints still work for existing integrations and are deprecated, but not currently scheduled for removal — the v1 list endpoint in particular returns raw upstream UPPER_SNAKE_CASE keys (e.g. FINDING_ID), inconsistent with the rest of this API.
Every field returned by these endpoints is described in the Swagger UI's schema definitions (Finding, FindingCreate, FindingUpdateRequestBody, etc.) — this page focuses on what each endpoint does and behavior that isn't obvious from the request/response shape alone. Each section below links straight to that endpoint's entry in the Swagger UI.
Authentication
Requests need an Authorization header carrying either an Atlas API access key or an OAuth-issued bearer token (see Getting API Credentials):
curl -H 'Authorization: <token>' 'https://api.esentire.com/finding/v2/findings'
read-data scope covers all GET endpoints below; write-data covers creating and updating findings.
Endpoints
Findings
List findings — GET /v2/findings
Returns a paginated list of findings, matching JSON-encoded query/sorts and limit/offset (or page/per_page) query parameters. When query is omitted, defaults to [{"field":"STATE","op":"in","value":["Open"]}]. Always evaluated within a date range: start_date/end_date default to the last 1 year when omitted — the upstream backend returns no results at all without one, so supply your own dates if you're using a custom query that needs a wider window. Supersedes the deprecated v1 GET /findings.
curl -G -H 'Authorization: <token>' \
--data-urlencode 'query=[{"field":"SEVERITY","op":"in","value":["Critical","High"]}]' \
--data-urlencode 'start_date=2026-01-01' \
'https://api.esentire.com/finding/v2/findings'
Get finding details — GET /v2/findings/{finding_id}
Returns a single finding by its finding_id (the event_id/FINDING_ID from the list response). Its evidence field can be stale or empty for findings whose evidence was most recently changed via an update rather than a full replace — use GET .../events for authoritative, up-to-date evidence. Supersedes the deprecated v1 GET /findings/{finding_id}.
Create a finding — POST /v2/findings
client.client_code must match your authenticated customer code (case-insensitive) or the request returns 400.
curl -X POST -H 'Authorization: <token>' -H 'Content-Type: application/json' \
-d '{
"category": "Suspicious",
"client": {"client_code": "ACME"},
"created_by": {"name": "Jane Doe", "email_address": "jane.doe@example.com", "organization": "ACME Corp"},
"ess_version": "1.5",
"event_created": "2026-01-15T10:30:00Z",
"event_type": "finding",
"evidence": [{"category": "event", "name": "Suspicious login", "summary": "Login from an unfamiliar location"}],
"related_entities": {"users": [{"email_address": "user@acme.com"}]},
"state": "Open",
"summary": "Suspicious login detected from an unfamiliar location"
}' \
'https://api.esentire.com/finding/v2/findings'
Update a finding — PATCH /v2/findings/{finding_id}
Every field in the request body is optional, but the body itself is required, and unrecognized fields are rejected. If client is omitted it defaults to your own customer code; if supplied, it must match your authenticated customer code (case-insensitive) or the request returns 400. No separate /update path segment here, unlike the legacy route. Supersedes the deprecated v1 PATCH /findings/{finding_id}/update.
curl -X PATCH -H 'Authorization: <token>' -H 'Content-Type: application/json' \
-d '{
"state": "Resolved",
"resolution_strategy": "Remediated",
"resolution_details": "Confirmed benign; access revoked."
}' \
'https://api.esentire.com/finding/v2/findings/54310d3a-a297-4a61-864b-62f5f7f90f0c'
Sub-resources (v2-only, no v1 equivalent)
Activity log — GET /v2/findings/{finding_id}/activity-logs
State/field change history for a finding.
Events — GET /v2/findings/{finding_id}/events
The evidence/timeline events for a finding — the authoritative, up-to-date source for a finding's evidence (prefer this over the possibly-stale evidence field on GET /v2/findings/{finding_id}).
Related alerts — GET /v2/findings/{finding_id}/related-alerts
Alerts/signals related to a finding.
Case comments & emails (v2-only, no v1 equivalent)
case_id is the service-desk case a finding was escalated to, not the finding_id — check a finding's own case field first and only call these when one is present. If case_id doesn't correspond to an existing, accessible case, the response is 400 — there's no separate empty-list case.
List case comments — GET /v2/findings/{case_id}/comments
Backed by the same data as the Tickets API's GET /v2/cases/{ticket_id}/comments.
List case emails — GET /v2/findings/{case_id}/emails
Backed by the same data as the Tickets API's GET /v2/cases/{ticket_id}/emails.
Health & metadata
API info — GET /info
Returns the deployed API's name, title and version.
Connectivity check — GET /test
A lightweight connectivity check with an empty response body.
Neither endpoint needs anything beyond a valid token.
Related APIs
- Tickets API - Ticket and case management
- MVS API - Vulnerability management
- Base API Reference - General API concepts