API Keys & REST API

API keys allow programmatic access to BugDrop — for the CLI, custom integrations, and CI/CD pipelines. Managed from Settings → Developer & API tab.

CREATING AN API KEY

API keys are created with scoped permissions and optional expiration. The creation form matches the real app exactly:

Name

Scopes (comma separated)

Expires At (optional)

Only shown once

Copy your API key immediately after creation. It cannot be retrieved again — only rotated or revoked.

AVAILABLE SCOPES

project:read: Read project metadata, members, and settings
project:write: Create, update, or delete projects
annotation:read: List and fetch annotations
annotation:write: Create, update, or delete annotations
build:create: Trigger new builds for a project
build:read: List build history and view build logs
webhook:write: Create and manage outbound webhooks
workspace:read: Read workspace-level stats and configuration

workspace:read includes

Workspace stats, project listings, and organization-level metadata used by dashboards and internal automation scripts.

API KEY LIST

The key list shows name, prefix, expiration, and last used timestamp. Each key has a Manage dropdown with Rotate and Revoke actions.

Name	Prefix	Expires	Last Used	Actions
Local Dev CLI	sk-bd-dev...	Never	Just now
CI / GitHub Actions	sk-bd-ci...	Mar 20, 2026	2h ago

Rotate vs Revoke

Rotate generates a new key with the same name and scopes — the old key is immediately invalidated. Revoke permanently deletes the key.

REST API — BASE URL

bash

BASE_URL: https://api.bugdrop.io/api/v1
Authorization: Bearer sk-bd-<your-api-key>

GET /annotations: List annotations with filter params (?status=open&severity=high)
GET /annotations/:id: Fetch a single annotation
PATCH /annotations/:id: Update status, severity, assignee, or custom fields
POST /projects/:projectId/annotations/:annotationId/links: Create annotation link (related/blocks/blocked_by/duplicates)
DELETE /projects/:projectId/annotations/:annotationId/links/:linkId: Remove annotation link
DELETE /annotations/:id: Soft-delete an annotation
POST /projects/:id/builds: Trigger a new build for a project
GET /projects/:id/builds: List build history
GET /workspace/stats: Get workspace-level annotation and project stats

EXAMPLE — LIST OPEN ANNOTATIONS

curl

bash

curl -X GET \
  "https://api.bugdrop.io/api/v1/annotations?status=open&severity=high" \
  -H "Authorization: Bearer sk-bd-<your-key>"
# Response
{
  "data": [
    {
      "id": "ann_01HZ...",
      "title": "Button not clickable on mobile",
      "status": "open",
      "severity": "high",
      "pageUrl": "/checkout",
      "aiFixReady": true
    }
  ],
  "pagination": { "page": 1, "total": 12 }
}