> ## Documentation Index > Fetch the complete documentation index at: https://docs.truu.ai/llms.txt > Use this file to discover all available pages before exploring further. # List hydrated cases with threat events > Returns cases scoped to the caller's domain. Each case includes the full threat event objects referenced by `event_ids`, so external systems can process a case without making a second `/threats` lookup. For polling integrations, use `created_after` with an ISO 8601 timestamp to query cases created within a specific time window, for example: `GET /cases?created_after=2026-06-15T00:00:00Z`. **Side effect:** Any `discover` case included in the response is automatically claimed — it transitions to `pending_investigation` and an investigation record is created. Repeated polling of the same case is safe; already-claimed cases are not double-counted. ## OpenAPI ````yaml https://eris.devops.truu.ai/api/v1/external/docs get /cases openapi: 3.0.3 info: title: TOTAL Public API version: 2.3.10 description: > The TOTAL API gives you programmatic access to your organization's security data. Use it to query cases and threat events, and to feed verdicts back into the platform. ## Authentication All routes in this specification are served under `/api/v1/external` and require a domain-scoped API key via the `X-API-Key` header. Generate and manage keys from the API Keys page in Settings. The admin console (Atlas) uses separate JWT-authenticated routes under `/api/v1/eris/...` (for example `GET /api/v1/eris/integrations`); those are not part of this public API surface. ## Pagination List routes use cursor pagination: `page_size` (default 50, max 200) and optional `next_cursor` (pass the `case_id` or `event_id` UUID from the last item of the previous page). Responses include `next_cursor` when more results are available. ## Rate Limits Read endpoints in this API are limited to 1,000 requests/minute. Write endpoints in this API are limited to 200 requests/minute. ## Availability Some routes may return `423 Locked` when the requested data is not yet available for your domain. --- ## Appendix A — Azure Log Analytics: source_event_ids → KQL lookup Threat events include a `source_event_ids` array. Each value is the `_ItemId` of the originating row in your Azure Log Analytics workspace — the per-row GUID stamped by Log Analytics at ingest. It is row-unique on every supported table, so the same lookup pattern works regardless of source: | where _ItemId == "" Run the lookup against your Log Analytics workspace (the same workspace that backs Azure Log Analytics / Defender XDR Advanced Hunting). Use the `source` field on the event to pick the table. | Source table | KQL field | Example KQL | |---|---|---| | SigninLogs | _ItemId | `SigninLogs | where _ItemId == ""` | | AuditLogs | _ItemId | `AuditLogs | where _ItemId == ""` | | AADUserRiskEvents | _ItemId | `AADUserRiskEvents | where _ItemId == ""` | | CloudAppEvents | _ItemId | `CloudAppEvents | where _ItemId == ""` | | OfficeActivity | _ItemId | `OfficeActivity | where _ItemId == ""` | | EmailEvents | _ItemId | `EmailEvents | where _ItemId == ""` | | EmailPostDeliveryEvents | _ItemId | `EmailPostDeliveryEvents | where _ItemId == ""` | | EmailUrlInfo | _ItemId | `EmailUrlInfo | where _ItemId == ""` | | EmailAttachmentInfo | _ItemId | `EmailAttachmentInfo | where _ItemId == ""` | | UrlClickEvents | _ItemId | `UrlClickEvents | where _ItemId == ""` | | SecurityEvent | _ItemId | `SecurityEvent | where _ItemId == ""` | | IdentityLogonEvents | _ItemId | `IdentityLogonEvents | where _ItemId == ""` | | IdentityQueryEvents | _ItemId | `IdentityQueryEvents | where _ItemId == ""` | | IdentityDirectoryEvents | _ItemId | `IdentityDirectoryEvents | where _ItemId == ""` | | BehaviorAnalytics | _ItemId | `BehaviorAnalytics | where _ItemId == ""` | | Anomalies | _ItemId | `Anomalies | where _ItemId == ""` | | AzureActivity | _ItemId | `AzureActivity | where _ItemId == ""` | | MicrosoftPurviewInformationProtection | _ItemId | `MicrosoftPurviewInformationProtection | where _ItemId == ""` | | CommonSecurityLog | _ItemId | `CommonSecurityLog | where _ItemId == ""` | | Syslog | _ItemId | `Syslog | where _ItemId == ""` | | AADProvisioningLogs | _ItemId | `AADProvisioningLogs | where _ItemId == ""` | servers: - url: https://eris.devops.truu.ai/api/v1/external description: TOTAL Public API security: - ApiKeyAuth: [] tags: - name: Cases description: Threat investigation cases and verdicts - name: Users description: Provisioned users and monitoring - name: Personas description: Persona overviews - name: Threats description: Raw threat events paths: /cases: get: tags: - Cases summary: List hydrated cases with threat events description: | Returns cases scoped to the caller's domain. Each case includes the full threat event objects referenced by `event_ids`, so external systems can process a case without making a second `/threats` lookup. For polling integrations, use `created_after` with an ISO 8601 timestamp to query cases created within a specific time window, for example: `GET /cases?created_after=2026-06-15T00:00:00Z`. **Side effect:** Any `discover` case included in the response is automatically claimed — it transitions to `pending_investigation` and an investigation record is created. Repeated polling of the same case is safe; already-claimed cases are not double-counted. operationId: listCasesWithThreatEvents parameters: - name: email in: query schema: type: string description: Filter by user email or UPN. - name: tuid in: query schema: type: string format: uuid description: >- Filter by TOTAL user identifier. If combined with email, both must refer to the same user. - name: case_id in: query schema: type: string format: uuid - name: state in: query schema: $ref: '#/components/schemas/CaseState' - name: threat_type in: query schema: $ref: '#/components/schemas/ThreatType' - name: created_after in: query schema: type: string format: date-time description: >- Return cases whose `created_at` is greater than or equal to this timestamp. - name: created_before in: query schema: type: string format: date-time description: >- Return cases whose `created_at` is less than or equal to this timestamp. - name: page_size in: query schema: type: integer default: 50 maximum: 200 - name: next_cursor in: query schema: type: string format: uuid description: Case id from the last item of the previous page. responses: '200': description: Cursor-paginated list of hydrated cases with full threat events content: application/json: schema: allOf: - $ref: '#/components/schemas/CursorPage' - type: object properties: data: type: array items: $ref: '#/components/schemas/ExternalCase' '400': description: Invalid query (e.g. invalid next_cursor) content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient scope — cases:read required content: application/json: schema: $ref: '#/components/schemas/Error' '423': description: Resource not ready yet for this domain content: application/json: schema: $ref: '#/components/schemas/ResourceNotReady' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CaseState: type: string description: | Lifecycle state of a case: - `discover` — Vetted by the AI judge, ready for triage - `pending_investigation` — Swiped; investigation pending - `investigating` — Investigation underway - `enforced` — An enforcement action has been taken - `closed` — Case closed ThreatType: type: string description: | Case classification from the AI judge (Predict / inference pipeline). Known values: `threat`, `insider_threat`, `identity_vulnerability`. Older or demo rows may still carry legacy strings until backfilled. CursorPage: type: object properties: next_cursor: type: string nullable: true ExternalCase: type: object description: Case shape returned by the external API (hydrated with events). properties: case_id: type: string format: uuid tuid: type: string format: uuid nullable: true description: TOTAL user identifier, shared with persona endpoints. user_email: type: string nullable: true user_name: type: string nullable: true threat_type: $ref: '#/components/schemas/ThreatType' nullable: true threat_brief: type: string nullable: true created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true closed_at: type: string format: date-time nullable: true events: type: array items: $ref: '#/components/schemas/CaseEvent' Error: type: object properties: error: type: string ResourceNotReady: type: object properties: error: type: string description: Always `resource_not_ready` resource: type: string description: One of `cases`, `threats`, `personas` message: type: string description: Human-readable readiness status message details: type: string description: Resource-specific not-ready detail days_until_ready: type: number format: float description: Days remaining until the resource is available external_api_enabled_at_utc: type: string format: date-time now_utc: type: string format: date-time CaseEvent: type: object description: Threat event shape embedded inside a hydrated case. properties: event_id: type: string format: uuid kind: type: string description: Always `threat` tuid: type: string format: uuid nullable: true description: TOTAL user identifier, shared with persona endpoints. category: type: array items: type: string nullable: true description: Category tags from the source system (freeform strings). subcategory: type: array items: type: string nullable: true title: type: string nullable: true summary: type: string nullable: true source: type: string nullable: true description: Connector or platform identifier (not a closed enum). source_table: type: string nullable: true description: Originating source-system table or stream identifier. source_event_ids: type: array items: type: string nullable: true description: Source-system event identifiers linked to this threat. user_name: type: string nullable: true user_email: type: string nullable: true created_at: type: string format: date-time nullable: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: | Domain-scoped API key. Generate and manage keys from the API Keys page in Settings. Accepted in two forms: - `X-API-Key: ` header (preferred) - `Authorization: Bearer ` header (also accepted) ````