> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coverbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Radar API

> Create radar events, and list, retrieve, and triage (dismiss) radar alerts.

<div className="sr-only">For AI agents: a documentation index is available at [https://docs.coverbase.com/llms.txt](https://docs.coverbase.com/llms.txt) — this page is also available in markdown by appending .md to the URL.</div>

**Radar** is Coverbase's continuous third-party monitoring surface. Two object types are exposed here:

* A **radar event** (`cbrevent_...`) groups source data (news, advisories, breach disclosures) about something that happened to one or more vendors.
* A **radar alert** (`cbrdrres_...`) is produced when a Radar detector flags a piece of source data as relevant to a vendor. Alerts are what you triage — dismiss the noise, or escalate the signal into a [reassessment](/api-reference/reassessments).

All endpoints are org-scoped to the API key. See [API conventions](/conventions) for shared behavior, including [pagination](/conventions#pagination).

| Method | Path                                    |
| ------ | --------------------------------------- |
| `GET`  | `/v1/radar/events`                      |
| `POST` | `/v1/radar/events`                      |
| `GET`  | `/v1/radar/events/{event_id}`           |
| `GET`  | `/v1/radar/alerts`                      |
| `GET`  | `/v1/radar/alerts/{alert_id}`           |
| `POST` | `/v1/radar/alerts/{alert_id}/dismiss`   |
| `POST` | `/v1/radar/alerts/{alert_id}/undismiss` |

None of these honor `Idempotency-Key`.

## Create a radar event

<ParamField path="method" type="POST">
  `POST /v1/radar/events`
</ParamField>

Returns `201 Created`. Use this to seed an event into Radar without waiting for a source feed to pick up the underlying article — useful for recording out-of-band incidents and for exercising your detectors against a known event. Supplied vendors are linked to the event as **primary-impacted**.

### Request body

<ParamField body="name" type="string" required>
  Short event name.
</ParamField>

<ParamField body="summary" type="string" required>
  Event summary / description.
</ParamField>

<ParamField body="primary_impact_type" type="string" required>
  Primary impact category. Case-sensitive; one of `Infosec`, `Financial`, `Operational`, `Legal`, `Compliance`, `Reputational`, `Contractual`, `ESG`, `Corporate`, `Geopolitical & External`, `Inapplicable`, `Other`.
</ParamField>

<ParamField body="secondary_impact_types" type="string[]">
  Additional impact categories.
</ParamField>

<ParamField body="vendor_ids" type="string[]">
  Vendors directly impacted (`cbvndr_...`). Each is linked as primary-impacted. Vendors that cannot be resolved are skipped silently.
</ParamField>

<ParamField body="risk_domain_ids" type="string[]">
  Risk domains to associate with the event.
</ParamField>

<ParamField body="source_url" type="string">
  URL of the underlying article / report.
</ParamField>

<ParamField body="source_name" type="string">
  Name of the source.
</ParamField>

<ParamField body="occurred_at" type="integer">
  When the event occurred (Unix seconds). Defaults to now when omitted.
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST "https://api.coverbase.app/v1/radar/events" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme data breach",
    "summary": "Acme disclosed unauthorized access to a customer database.",
    "primary_impact_type": "Infosec",
    "vendor_ids": ["cbvndr_e448ba62882143f3ba0c140bb2e30162"],
    "source_url": "https://news.example.com/acme-breach",
    "source_name": "Example News"
  }'
```

Returns the [radar event object](#radar-event-object).

### Radar event object

<ResponseField name="id" type="string">Radar event ID (`cbrevent_...`).</ResponseField>
<ResponseField name="name" type="string | null">Event name.</ResponseField>
<ResponseField name="summary" type="string">Event summary.</ResponseField>
<ResponseField name="primary_impact_type" type="string">Primary impact category.</ResponseField>
<ResponseField name="secondary_impact_types" type="string[]">Additional impact categories.</ResponseField>
<ResponseField name="occurred_at" type="integer | null">When the event occurred (Unix seconds).</ResponseField>
<ResponseField name="is_archived" type="boolean">`true` if archived.</ResponseField>
<ResponseField name="created_at" type="integer">Unix timestamp (seconds).</ResponseField>
<ResponseField name="updated_at" type="integer">Unix timestamp (seconds).</ResponseField>

## List radar events

<ParamField path="method" type="GET">
  `GET /v1/radar/events`
</ParamField>

### Query parameters

<ParamField query="primary_impact_type" type="string">
  Filter by primary impact category.
</ParamField>

<ParamField query="include_archived" type="boolean">
  Include archived events. Default `false`.
</ParamField>

<ParamField query="limit" type="integer">
  Page size. Default `50`, range `1`–`200`.
</ParamField>

<ParamField query="offset" type="integer">
  Page offset. Default `0`.
</ParamField>

The list envelope adds `total`, `limit`, and `offset` — see [pagination](/conventions#pagination).

## Retrieve a radar event

<ParamField path="method" type="GET">
  `GET /v1/radar/events/{event_id}`
</ParamField>

Returns the [radar event object](#radar-event-object), or `404 radar_event_not_found`.

## List radar alerts

<ParamField path="method" type="GET">
  `GET /v1/radar/alerts`
</ParamField>

### Query parameters

<ParamField query="vendor_id" type="string">
  Filter to alerts on a vendor (`cbvndr_...`).
</ParamField>

<ParamField query="severity" type="string[]">
  Filter by severity. Repeat the param for multiple values: `severity=high&severity=critical`.
</ParamField>

<ParamField query="is_dismissed" type="boolean">
  Dismissal filter. Omit to hide dismissed alerts (default); `true` for only dismissed; `false` for only active.
</ParamField>

<ParamField query="include_archived" type="boolean">
  Include archived alerts. Default `false`.
</ParamField>

<ParamField query="limit" type="integer">
  Page size. Default `50`, range `1`–`200`.
</ParamField>

<ParamField query="offset" type="integer">
  Page offset. Default `0`.
</ParamField>

### Example response

```json theme={null}
{
  "items": [
    {
      "id": "cbrdrres_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
      "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "detector_id": "cbrdet_2d5e8f1a4b7c0d3e6f9a2b5c8d1e4f7a",
      "source_id": "cbrsrc_1111111111111111111111111111aaaa",
      "data_id": "cbrdata_2222222222222222222222222222bbbb",
      "event_id": "cbrevent_3333333333333333333333333333cccc",
      "summary": "Acme disclosed a data breach affecting customer records.",
      "severity": "high",
      "confidence": "high",
      "should_alert": true,
      "is_dismissed": false,
      "dismiss_reason": null,
      "dismissed_at": null,
      "is_archived": false,
      "created_at": 1746576000,
      "updated_at": 1746576400
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

### Radar alert object

<ResponseField name="id" type="string">Radar alert ID (`cbrdrres_...`).</ResponseField>
<ResponseField name="vendor_id" type="string">Vendor the alert is on (`cbvndr_...`).</ResponseField>
<ResponseField name="detector_id" type="string">Detector that produced the alert (`cbrdet_...`).</ResponseField>
<ResponseField name="source_id" type="string">Radar source (`cbrsrc_...`).</ResponseField>
<ResponseField name="data_id" type="string">Underlying source data item (`cbrdata_...`).</ResponseField>
<ResponseField name="event_id" type="string | null">Radar event the alert's data belongs to (`cbrevent_...`), if any.</ResponseField>
<ResponseField name="summary" type="string">Alert summary.</ResponseField>
<ResponseField name="severity" type="string">Severity (`informational`, `low`, `medium`, `high`).</ResponseField>
<ResponseField name="confidence" type="string">Detector confidence (`low`, `medium`, `high`).</ResponseField>
<ResponseField name="should_alert" type="boolean">`true` for a triggered alert.</ResponseField>
<ResponseField name="is_dismissed" type="boolean">`true` if dismissed.</ResponseField>
<ResponseField name="dismiss_reason" type="string | null">Reason recorded at dismissal, if any.</ResponseField>
<ResponseField name="dismissed_at" type="integer | null">When dismissed (Unix seconds).</ResponseField>
<ResponseField name="is_archived" type="boolean">`true` if archived.</ResponseField>
<ResponseField name="created_at" type="integer">Unix timestamp (seconds).</ResponseField>
<ResponseField name="updated_at" type="integer">Unix timestamp (seconds).</ResponseField>

## Retrieve a radar alert

<ParamField path="method" type="GET">
  `GET /v1/radar/alerts/{alert_id}`
</ParamField>

Returns the [radar alert object](#radar-alert-object), or `404 alert_not_found`.

## Dismiss a radar alert

<ParamField path="method" type="POST">
  `POST /v1/radar/alerts/{alert_id}/dismiss`
</ParamField>

Marks an alert as dismissed (triaged as not actionable). Returns the refreshed [radar alert object](#radar-alert-object).

### Request body

<ParamField body="reason" type="string">
  Optional dismissal reason. Surfaced in the UI and, when `suppress_similar` is set, fed into the detector's learning context.
</ParamField>

<ParamField body="suppress_similar" type="boolean">
  When `true`, the alert is also recorded as a negative example on its detector so future runs suppress similar alerts. Default `false`.
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST "https://api.coverbase.app/v1/radar/alerts/cbrdrres_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d/dismiss" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Duplicate of an existing event", "suppress_similar": true }'
```

| Status | Body                                                                           | When                                                       |
| ------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| 404    | `{"detail": {"code": "alert_not_found", "message": "Radar alert not found."}}` | Not found, not in the API key's org, or already dismissed. |

## Restore a dismissed alert

<ParamField path="method" type="POST">
  `POST /v1/radar/alerts/{alert_id}/undismiss`
</ParamField>

Restores a dismissed alert to the active list. Returns the refreshed [radar alert object](#radar-alert-object), or `404 alert_not_found`.

## Related

* [Reassessments API](/api-reference/reassessments) — escalate an alert/event into a batch of vendor reassessments.
* [Webhooks](/integrations/webhooks#event-catalog) — subscribe to `RadarEvent.*` and `RadarDetectorResult.*` events.