DebugBundle
API

API

RESTful API for event ingestion, incident retrieval, hosted health checks, webhook management, token management, and more. Authenticated via project tokens, member tokens, or browser sessions.

Base URL

https://api.debugbundle.com

Self-hosted deployments use your custom domain.

Authentication

The API uses three authentication methods, each scoped differently:

MethodHeader / MechanismScopeUse Case
Project tokenAuthorization: Bearer dbundle_proj_*Write-only ingestionSDKs sending events via POST /v1/events
Member tokenAuthorization: Bearer dbundle_mem_*Full read/manageCLI, API clients, MCP — incidents, webhooks, tokens, billing
Browser sessionCookie: dbundle_session=*Full read/manageWeb dashboard (same permissions as member token)

Project tokens can only ingest events. They cannot read incidents, manage webhooks, or perform any other operation.

See Authentication for details.

Request Format

  • Content-Type: application/json
  • Character encoding: UTF-8
  • All request bodies are JSON objects validated with Zod at the boundary
  • Unknown fields are rejected (strict schemas)

Response Format

Success

{
  "incidents": [...],
  "next_cursor": "2025-01-15T10:30:00.000Z|inc_abc123"
}

Error

{
  "error": "invalid_member_token"
}

Error codes are machine-readable string identifiers, not numeric codes.

Ingestion Response

POST /v1/events returns a different shape:

{
  "accepted": 8,
  "rejected": 2,
  "errors": [
    { "index": 3, "reason": "invalid_event" },
    { "index": 7, "reason": "rate_limited" }
  ]
}

Pagination

List endpoints use cursor-based pagination:

ParameterTypeDefaultDescription
limitinteger20Page size (1–100)
cursorstring—Opaque cursor from next_cursor in previous response

When more results exist, the response includes next_cursor. When no more results exist, next_cursor is null.

# First page
curl -H "Authorization: Bearer dbundle_mem_xxx" \
  "https://api.debugbundle.com/v1/incidents?limit=10"

# Next page
curl -H "Authorization: Bearer dbundle_mem_xxx" \
  "https://api.debugbundle.com/v1/incidents?limit=10&cursor=2025-01-15T10:30:00.000Z|inc_abc123"

Rate Limiting

Event ingestion is rate-limited per project token. The limit depends on your plan tier:

TierRate Limit
Free60 events/min
Solo300 events/min
Team1,000 events/min

When rate-limited, events are rejected with reason "rate_limited" in the errors array. The SDK automatically handles backoff.

Management endpoints (incidents, webhooks, tokens) are not rate-limited in the current version.

HTTP Status Codes

CodeMeaning
200Success
201Resource created
204Success, no content
400Invalid request (malformed body, invalid query parameters)
401Authentication failed (missing, invalid, or wrong token type)
403Insufficient permissions (e.g., member trying owner-only operation)
404Resource not found
409Conflict (e.g., duplicate email at signup)
429Rate limited
500Internal server error

Endpoint Index

Ingestion

MethodPathAuthDescription
POST/v1/eventsProject tokenIngest event batch

Incidents

MethodPathAuthDescription
GET/v1/incidentsMember tokenList incidents
GET/v1/incidents/:idMember tokenGet incident detail
POST/v1/incidents/:id/resolveMember tokenResolve an incident
POST/v1/incidents/resolveMember tokenResolve incidents in bulk
POST/v1/incidents/:id/reopenMember tokenReopen an incident
POST/v1/incidents/reopenMember tokenReopen incidents in bulk
GET/v1/incidents/:id/bundleMember tokenRetrieve debug bundle
GET/v1/incidents/:id/reproductionMember tokenRetrieve reproduction artifacts
GET/v1/incidents/:id/logsMember tokenList event logs

Services

MethodPathAuthDescription
GET/v1/servicesMember tokenList services for a project

Webhooks

MethodPathAuthDescription
GET/v1/webhooksMember tokenList webhooks
POST/v1/webhooksMember tokenCreate webhook
GET/v1/webhooks/:idMember tokenGet webhook
PATCH/v1/webhooks/:idMember tokenUpdate webhook
DELETE/v1/webhooks/:idMember tokenDelete webhook
POST/v1/webhooks/:id/testMember tokenSend test delivery
GET/v1/webhooks/:id/deliveriesMember tokenList deliveries
POST/v1/webhooks/:id/deliveries/:did/retryMember tokenRetry delivery

Alerts

MethodPathAuthDescription
GET/v1/alertsMember tokenList alert rules
POST/v1/alertsMember tokenCreate alert rule
PATCH/v1/alerts/:idMember tokenUpdate alert rule
DELETE/v1/alerts/:idMember tokenDelete alert rule

Availability Checks

MethodPathAuthDescription
GET/v1/projects/:id/availability-checksBrowser session or member tokenList hosted health checks and plan limits
POST/v1/projects/:id/availability-checksBrowser session or member token (owner/admin)Create a hosted health check
GET/v1/projects/:id/availability-checks/:checkIdBrowser session or member tokenGet one hosted health check
PATCH/v1/projects/:id/availability-checks/:checkIdBrowser session or member token (owner/admin)Update a hosted health check
DELETE/v1/projects/:id/availability-checks/:checkIdBrowser session or member token (owner/admin)Delete a hosted health check
POST/v1/projects/:id/availability-checks/testBrowser session or member token (owner/admin)Run a side-effect-free target test
GET/v1/projects/:id/availability-checks/:checkId/resultsBrowser session or member tokenList recent raw execution results
GET/v1/projects/:id/availability-checks/:checkId/daily-rollupsBrowser session or member tokenList retained per-day status history

See Availability Checks for behavior, tier limits, SSRF guardrails, and CLI/MCP parity.

Tokens

MethodPathAuthDescription
GET/v1/projects/:id/tokensMember tokenList project tokens
POST/v1/projects/:id/tokensMember tokenCreate project token
POST/v1/projects/:id/tokens/:tokenId/revokeMember tokenRevoke project token
GET/v1/member/tokensMember tokenList member tokens
POST/v1/member/tokensMember tokenCreate member token
POST/v1/member/tokens/:tokenId/revokeMember tokenRevoke member token

Projects

MethodPathAuthDescription
GET/v1/projectsMember tokenList projects
POST/v1/projectsMember tokenCreate project
GET/v1/projects/:idMember tokenGet project
PATCH/v1/projects/:idMember tokenUpdate project
DELETE/v1/projects/:idMember tokenDelete project

Members

MethodPathAuthDescription
GET/v1/projects/:id/membersMember token (owner/admin)List project members
GET/v1/projects/:id/invitesMember token (owner/admin)List pending project invites
POST/v1/projects/:id/inviteMember token (owner/admin)Invite a collaborator
DELETE/v1/projects/:id/invites/:inviteIdMember token (owner/admin)Cancel a project invite
PATCH/v1/projects/:id/members/:userIdMember token (owner/admin)Update project member role
DELETE/v1/projects/:id/members/:userIdMember token (owner/admin)Remove a project member

Billing

MethodPathAuthDescription
GET/v1/billingBrowser session or member token (owner)Get billing summary
POST/v1/billing/trial/startBrowser session or member token (owner)Start an eligible no-card trial
POST/v1/billing/capacity/increaseBrowser session or member token (owner)Add capacity units
POST/v1/billing/capacity/scheduled-reductionBrowser session or member token (owner)Schedule capacity reduction
DELETE/v1/billing/capacity/scheduled-reductionBrowser session or member token (owner)Cancel pending reduction

Probes

MethodPathAuthDescription
GET/v1/sdk/configProject tokenGet SDK config, including capture policy, active capture rules, and active probe directives
GET/v1/projects/:id/probesMember tokenList active probes for a project
POST/v1/projects/:id/probes/activateMember tokenActivate a remote probe
POST/v1/projects/:id/probes/deactivateMember tokenDeactivate a remote probe

Capture Policy

MethodPathAuthDescription
GET/v1/projects/:id/capture-policyMember tokenGet current capture policy for a project; plain members receive preview-only output
PATCH/v1/projects/:id/capture-policyMember token (owner/admin)Set capture policy for a project

Capture Rules

MethodPathAuthDescription
GET/v1/projects/:id/capture-rulesMember tokenList project capture rules; plain members receive preview-only output
POST/v1/projects/:id/capture-rulesMember token (owner/admin)Create a capture rule
PATCH/v1/projects/:id/capture-rules/:ruleIdMember token (owner/admin)Update a capture rule
DELETE/v1/projects/:id/capture-rules/:ruleIdMember token (owner/admin)Delete a capture rule
POST/v1/incidents/:id/capture-rule-suggestionMember tokenSuggest capture rules from an incident bundle
POST/v1/incidents/:id/capture-rulesMember token (owner/admin)Create a capture rule from an incident suggestion

Authentication

MethodPathAuthDescription
POST/v1/auth/request-codeNoneRequest a one-time email code
POST/v1/auth/verify-codeNoneVerify a one-time email code and create a browser session
GET/v1/auth/sessionSessionResolve current browser session
POST/v1/auth/logoutSessionEnd session
GET/v1/auth/github/startNoneStart GitHub OAuth
GET/v1/auth/github/callbackNoneComplete GitHub OAuth
POST/v1/auth/github/device/startNoneStart GitHub device flow for CLI bootstrap
POST/v1/auth/github/device/pollNonePoll GitHub device-flow status
POST/v1/auth/github/device/claimNoneClaim the issued member token after approval
POST/v1/auth/github/token/exchangeNoneExchange an existing GitHub access token for a member token

Next Steps

Alert Management

Configure alert channels and conditions with the DebugBundle CLI.

Authentication

Authenticate with the DebugBundle API using project tokens, member tokens, or browser sessions. Learn when to use each and how to create them.

On this page

Base URLAuthenticationRequest FormatResponse FormatSuccessErrorIngestion ResponsePaginationRate LimitingHTTP Status CodesEndpoint IndexIngestionIncidentsServicesWebhooksAlertsAvailability ChecksTokensProjectsMembersBillingProbesCapture PolicyCapture RulesAuthenticationNext Steps