Vault Radar events (API)

Overview

The HCP Vault Radar event API provides endpoints for querying and managing security events detected by Vault Radar. Events represent security findings such as leaked secrets, exposed credentials, and other vulnerabilities discovered across various data sources.

Versioning

The Vault Radar API version is 2023-05-01.

Prerequisites

• Retrieve an access token for authentication.

Search

POST /2023-05-01/vault-radar/projects/{project_id}/events/search

Search for events based on flexible criteria including filtering, sorting, and pagination.

https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/{project_id}/events/search

Request

Path parameters

project_id (string, required): The unique identifier of the HCP project where you enabled Vault Radar. You can find the project ID in the URL of your browser or in the project settings in the HCP Portal.

Example body

{
  "search": {
    "filters": [
      {
        "id": "status",
        "op": "EQ",
        "value": [
          "NEW",
          "NOTIFIED",
          "TO_REMEDIATE",
          "SECRET_STORED",
          "SECRET_REPLACED",
          "SECRET_REVOKED"
        ]
      },
      {
        "id": "severity",
        "op": "EQ",
        "value": [
          "critical",
          "high"
        ]
      },
      {
        "id": "in_latest_version",
        "value": [
          true
        ],
        "op": "EQ"
      }
    ],
    "orderBy": "created",
    "orderDirection": "DESC",
    "limit": 100,
    "page": 1
  }
}

Response

200 - OK

{
  "events": [
    {
      "event_id": "7c7818b9-dce1-4abb-8f6e-2cd917c3531f",
      "type": "REPO_SCAN_MATCH",
      "sub_type": "secret_assignment",
      "severity": "critical",
      "status": "NEW",
      "created": "2025-12-20T22:15:06.667915Z",
      "in_latest_version": true,
      ...
    }
  ]
}

Search (group and aggregate)

POST /2023-05-01/vault-radar/projects/{project_id}/events/search

The search endpoint for events also allows you to group and aggregate results.

https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/{project_id}/events/search

Path parameters

project_id (string, required): The unique identifier of the HCP project where you enabled Vault Radar. You can find the project ID in the URL of your browser or in the project settings in the HCP Portal.

Example body

Group and count events by severity and status.

{
  "search": {
    "filters": [
      {
        "id": "in_latest_version",
        "value": [
          true
        ],
        "op": "EQ"
      }
    ],
    "groupBy": "severity,status"
  }
}

Response

200 - OK

{
  "events": [
    {
      "count": 5,
      "severity": "medium",
      "status": "NEW"
    },
    {
      "count": 4,
      "severity": "low",
      "status": "NEW"
    },
    {
      "count": 1,
      "severity": "info",
      "status": "IGNORE_RULE"
    }
  ]
}

Update events

PUT /2023-05-01/vault-radar/projects/{project_id}/events

Bulk update the status of multiple events for triaging and remediation workflows.

https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/{project_id}/events

Path parameters

project_id (string, required): The unique identifier of the HCP project where you enabled Vault Radar. You can find the project ID in the URL of your browser or in the project settings in the HCP Portal.

Example body

{
  "events": [
    {
      "event_id": "0b366a31-7494-4264-bf26-12931d323b5c",
      "status": "NOT_IMPORTANT"
    },
    {
      "event_id": "544c8754-2f63-4907-8b1d-58eff1b7353a",
      "status": "TO_REMEDIATE"
    },
    {
      "event_id": "8b5edc4b-95ff-4a96-8064-ed56cb54908b",
      "status": "RESOLVED"
    }
  ]
}

Response

200 - OK

{
  "count": 3
}

Search schema

The search events endpoint uses SearchSchemaV2 to define search criteria. This schema supports:

• Pagination: Control result sets with limit and page
• Filtering: Apply conditions using Event field names
• Sorting: Order results by Event field names
• Grouping: Aggregate events by specific Event field names

Search parameters

• limit (int32): Maximum number of results to return (max: 1000). Optional, defaults to 1000.
• page (int32): Page number for pagination (first page is 1). Optional, defaults to 1.
• filters (array of FilterV2): Filtering criteria. Optional.
• orderBy (string): Comma-delimited Event field name to sort by (e.g., "created", "severity", or multiple order by "severity, status"). Optional.
• orderDirection (string): Comma-delimited sort direction - "ASC" (ascending) or "DESC" (descending) e.g., "ASC", "DESC", or multiple directions "ASC, DESC". Optional.
• groupBy (string): Comma-delimited Event field names to aggregate and group results e.g., "severity", "status", or multiple group by "severity, status". Optional.

Filter structure

Each FilterV2 has three components:

• id (string): The Event field name to filter on (see Event Fields Reference below)
• value (array): Array of values to match against
• op (Operation enum): The comparison operation to use

When multiple filters are provided, they are combined using logical AND.

Available filter operations

• EQ: Equal - matches if the field equals any value in the array
• NEQ: Not Equal - matches if the field does not equal any value
• NEQ_NULL_AWARE: Not Equal to or null
• GT: Greater Than
• GE: Greater Than or Equal
• LT: Less Than
• LE: Less Than or Equal
• LIKE: Pattern matching (use % as wildcard)
• ILIKE: Case-insensitive pattern matching

Event fields reference

The event message contains the following fields that can be used for filtering, sorting, and grouping:

Fields

Best practices

Performance tips

• Use pagination with limit and page for large result sets
  • Maximum limit is 1000
  • Use page: 1 for first page, page: 2 for second, etc.
• Apply specific filters to reduce result size
• Use groupBy for aggregated views instead of fetching all events
• Combine filters with EQ operation for better performance than LIKE

Examples

Search for open events with high or critical severity.

$ curl -X POST \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/events/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "filters": [
        {"id": "status", "op": "EQ", "value": ["NEW", "NOTIFIED", "TO_REMEDIATE", "SECRET_STORED", "SECRET_REPLACED", "SECRET_REVOKED"]},
        {"id": "severity", "op": "EQ", "value": ["critical", "high"]}
      ],
      "orderBy": "created",
      "orderDirection": "DESC",
      "limit": 10,
      "page": 1
    }
  }'

Search with groupBy for event counts by severity and status.

$ curl -X POST \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/events/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "filters": [
        {"id": "in_latest_version", "value": [true], "op": "EQ"}
      ],
      "groupBy": "severity,status"
    }
  }'

Update the event status.

$ curl -X PUT \
  https://api.cloud.hashicorp.com/2023-05-01/vault-radar/projects/PROJECT_ID/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"event_id": "7c7818b9-dce1-4abb-8f6e-2cd917c3531f", "status": "RESOLVED"}
    ]
  }'

Additional resources

• HashiCorp Cloud Platform authentication documentation
• Vault Radar Swagger file