bugsink-helper

What this skill does

# Bugsink Helper Agent

## Overview

Bugsink is a self-hosted error tracking service compatible with Sentry SDKs. It provides a REST API for managing teams, projects, issues, events, and releases. There is no CLI tool; all operations use `curl` against the REST API.

## Authentication

```bash
# Set environment variables
export BUGSINK_URL="https://your-bugsink-instance.example.com"
export BUGSINK_TOKEN="your-api-token"
export API="$BUGSINK_URL/api/canonical/0"

# Auth header used in all requests
AUTH="Authorization: Bearer $BUGSINK_TOKEN"

# Verify authentication by listing teams
curl -s -H "$AUTH" "$API/teams/" | jq .
```

## API Endpoints Reference

| Resource   | Method | Path                                         | Required Params             |
| ---------- | ------ | -------------------------------------------- | --------------------------- |
| Teams      | GET    | `/api/canonical/0/teams/`                    | —                           |
| Teams      | POST   | `/api/canonical/0/teams/`                    | name (body)                 |
| Team       | GET    | `/api/canonical/0/teams/{uuid}/`             | —                           |
| Team       | PATCH  | `/api/canonical/0/teams/{uuid}/`             | —                           |
| Projects   | GET    | `/api/canonical/0/projects/`                 | — (optional `?team=<uuid>`) |
| Projects   | POST   | `/api/canonical/0/projects/`                 | team, name (body)           |
| Project    | GET    | `/api/canonical/0/projects/{id}/`            | —                           |
| Project    | PATCH  | `/api/canonical/0/projects/{id}/`            | —                           |
| Issues     | GET    | `/api/canonical/0/issues/`                   | `?project=<id>`             |
| Issue      | GET    | `/api/canonical/0/issues/{uuid}/`            | —                           |
| Events     | GET    | `/api/canonical/0/events/`                   | `?issue=<uuid>`             |
| Event      | GET    | `/api/canonical/0/events/{uuid}/`            | —                           |
| Stacktrace | GET    | `/api/canonical/0/events/{uuid}/stacktrace/` | —                           |
| Releases   | GET    | `/api/canonical/0/releases/`                 | `?project=<id>`             |
| Releases   | POST   | `/api/canonical/0/releases/`                 | project, version (body)     |
| Release    | GET    | `/api/canonical/0/releases/{uuid}/`          | —                           |

**Notes:**

- Team IDs and issue IDs are UUIDs. Project IDs are integers.
- DELETE is not supported (returns 405) on teams and projects.
- All list endpoints use cursor-based pagination.

---

## Team Operations

### List Teams

```bash
curl -s -H "$AUTH" "$API/teams/" | jq '.results'

# Summary output
curl -s -H "$AUTH" "$API/teams/" | \
  jq -r '.results[] | "\(.id)\t\(.name)\t\(.visibility)"'
```

### Create Team

```bash
curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/teams/" \
  -d '{
    "name": "Backend Team",
    "visibility": "joinable"
  }' | jq .
```

**Required fields:** `name` (string, max 255 chars)
**Optional fields:** `visibility` (enum: `joinable`, `discoverable`, `hidden`)

### Get Team Detail

```bash
curl -s -H "$AUTH" "$API/teams/$TEAM_UUID/" | jq .
```

### Update Team

```bash
curl -s -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
  "$API/teams/$TEAM_UUID/" \
  -d '{
    "name": "Renamed Team",
    "visibility": "hidden"
  }' | jq .
```

---

## Project Operations

### List Projects

```bash
curl -s -H "$AUTH" "$API/projects/" | jq '.results'

# Filter by team
curl -s -H "$AUTH" "$API/projects/?team=$TEAM_UUID" | jq '.results'

# Summary output
curl -s -H "$AUTH" "$API/projects/" | \
  jq -r '.results[] | "\(.id)\t\(.name)\t\(.slug)\t\(.visibility)"'
```

### Create Project

```bash
curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/projects/" \
  -d '{
    "team": "'$TEAM_UUID'",
    "name": "My App",
    "visibility": "team_members"
  }' | jq .
```

**Required fields:** `team` (UUID), `name` (string, max 255 chars)
**Optional fields:** `visibility` (enum: `joinable`, `discoverable`, `team_members`), `alert_on_new_issue` (bool), `alert_on_regression` (bool), `alert_on_unmute` (bool), `retention_max_event_count` (int, >= 0)

### Get Project Detail (includes DSN)

```bash
curl -s -H "$AUTH" "$API/projects/$PROJECT_ID/" | jq .

# Get just the DSN
curl -s -H "$AUTH" "$API/projects/$PROJECT_ID/" | jq -r '.dsn'
```

The project detail response includes `dsn`, `slug`, `digested_event_count`, and `stored_event_count` fields not present in the create/update schema.

### Update Project

```bash
curl -s -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
  "$API/projects/$PROJECT_ID/" \
  -d '{
    "name": "Renamed App",
    "alert_on_new_issue": true,
    "alert_on_regression": true
  }' | jq .
```

---

## Issue Operations

### List Issues (requires project filter)

```bash
# List issues for a project (required)
curl -s -H "$AUTH" "$API/issues/?project=$PROJECT_ID" | jq '.results'

# With sort and order
curl -s -H "$AUTH" "$API/issues/?project=$PROJECT_ID&sort=last_seen&order=desc" | jq '.results'

# Summary output
curl -s -H "$AUTH" "$API/issues/?project=$PROJECT_ID" | \
  jq -r '.results[:10][] | "\(.id)\t\(.calculated_type): \(.calculated_value)\t\(.digested_event_count) events\t\(.last_seen)"'
```

**Required query param:** `project` (integer project ID)
**Optional query params:**

- `sort`: `digest_order` (default) or `last_seen`
- `order`: `asc` (default) or `desc`
- `cursor`: pagination cursor

### Get Issue Detail

```bash
curl -s -H "$AUTH" "$API/issues/$ISSUE_UUID/" | jq .

# Formatted output
curl -s -H "$AUTH" "$API/issues/$ISSUE_UUID/" | \
  jq '{
    id,
    calculated_type,
    calculated_value,
    transaction,
    digested_event_count,
    stored_event_count,
    first_seen,
    last_seen,
    is_resolved,
    is_muted
  }'
```

---

## Event Operations

### List Events (requires issue filter)

```bash
# List events for an issue (required)
curl -s -H "$AUTH" "$API/events/?issue=$ISSUE_UUID" | jq '.results'

# Ascending order (oldest first)
curl -s -H "$AUTH" "$API/events/?issue=$ISSUE_UUID&order=asc" | jq '.results'

# Summary output
curl -s -H "$AUTH" "$API/events/?issue=$ISSUE_UUID" | \
  jq -r '.results[] | "\(.id)\t\(.event_id)\t\(.timestamp)"'
```

**Required query param:** `issue` (UUID)
**Optional query params:** `order` (`asc` or `desc`, default `desc`), `cursor`

**Note:** The list view omits the `data` field for performance. Use the detail endpoint for the full event payload.

### Get Event Detail

```bash
curl -s -H "$AUTH" "$API/events/$EVENT_UUID/" | jq .

# The detail view includes the full `data` payload and `stacktrace_md`
curl -s -H "$AUTH" "$API/events/$EVENT_UUID/" | jq '.data'
```

### Get Event Stacktrace (Markdown)

```bash
# Returns rendered stacktrace as Markdown text (text/markdown content type)
curl -s -H "$AUTH" "$API/events/$EVENT_UUID/stacktrace/"
```

This is the most useful endpoint for debugging. It returns a human-readable markdown rendering of the event's stacktrace including frames, source context, and local variables.

---

## Release Operations

### List Releases (requires project filter)

```bash
# List releases for a project (required)
curl -s -H "$AUTH" "$API/releases/?project=$PROJECT_ID" | jq '.results'

# Summary output
curl -s -H "$AUTH" "$API/releases/?project=$PROJECT_ID" | \
  jq -r '.results[] | "\(.id)\t\(.version)\t\(.date_released)"'
```

**Required query param:** `project` (integer project ID)

### Create Release

```bash
curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$API/releases/" \
  -d '{
    "project": '$PROJECT_ID',
    "version": "1.2.3",
    "timestamp": "2025-01-15T12:00:00Z"
  }' | jq .
```

**Required fields:** `project` (integer), `version` (string)
**Optional fields:** `timestamp` (datetime)

### Get Release Detail

```bash
curl -s -H "$