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

# Issues

Track delivery failures auto-grouped into actionable issues.

Issues are automatically created when delivery attempts fail. hookstream groups related failures into a single issue per destination and error type. Issues track occurrence counts, first/last seen timestamps, and resolution status. Issues auto-resolve after 30 minutes without new occurrences.

## List Issues

GET `/v1/issues`

List issues with optional status filter.

**Authentication:** API key or session cookie.

### Query Parameters

Filter by status: `open`, `acknowledged`, `resolved`, or `all`.

Filter by destination ID.

Number of results to return (max 100).

Offset for pagination.

```json 200 OK
{
  "issues": [
    {
      "id": "iss_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
      "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
      "destination_name": "Backend API",
      "status": "open",
      "first_seen_at": "2026-03-01T10:00:00Z",
      "last_seen_at": "2026-03-01T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

## Issue Summary

GET `/v1/issues/summary`

Get issue counts by status.

**Authentication:** API key or session cookie.

```json 200 OK
{ "open": 3, "acknowledged": 1, "resolved": 45 }
```

## Retrieve Issue

GET `/v1/issues/:id`

Get full issue detail including recent failed delivery attempt IDs.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "id": "iss_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
  "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "destination_name": "Backend API",
  "error_type": "http_5xx",
  "message": "Destination returned 503 Service Unavailable",
  "status": "open",
  "occurrence_count": 23,
  "first_seen_at": "2026-03-01T10:00:00Z",
  "last_seen_at": "2026-03-01T14:30:00Z",
  "recent_attempt_ids": ["da_aaa111", "da_bbb222", "da_ccc333"]
}
```

## Update Issue

PATCH `/v1/issues/:id`

Update an issue's status or snooze it until a specific time.

**Authentication:** API key or session cookie.

### Body Parameters

New status: `open`, `acknowledged`, or `resolved`.

ISO 8601 datetime to snooze the issue until, or `null` to unsnooze.

```bash cURL
curl -X PATCH https://hookstream.io/v1/issues/iss_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1 \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
```

```json 200 OK
{
  "id": "iss_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
  "status": "resolved",
  "resolved_at": "2026-03-01T15:00:00Z"
}
```

## Bulk Retry Issue

POST `/v1/issues/:id/retry`

Bulk retry all failed events associated with this issue.

**Authentication:** API key or session cookie.

```bash cURL
curl -X POST https://hookstream.io/v1/issues/iss_f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1/retry \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```json 200 OK
{ "retried": 23, "total": 23 }
```