API Overview

BugPin exposes a REST API for both the embeddable widget and programmatic admin access. The Widget API is public and uses API key authentication for submitting bug reports and fetching widget configuration. The Admin API requires session authentication and covers reports, projects, users, settings, and integrations. This page provides an overview of all endpoints, authentication methods, rate limiting, response formats, and CORS behavior.

Base URL

All API endpoints are relative to your BugPin server URL:

https://your-bugpin-server.com/api

API Categories

Widget API (Public)

The widget API is used by the embeddable widget and does not require session authentication. It uses API keys for project identification.

Endpoint	Method	Description
/api/widget/submit	POST	Submit a bug report
/api/widget/config/:apiKey	GET	Get widget configuration

See Widget API Reference for details.

Admin API (Authenticated)

The admin API requires session authentication and is used by the admin dashboard.

Endpoint	Description
/api/auth	Authentication (login, logout, session)
/api/reports	Bug report management
/api/projects	Project management
/api/users	User management
/api/settings	Application settings
/api/integrations	Third-party integrations (GitHub)

Authentication

Widget API

Widget endpoints use API keys for authentication:

# Via query parameter
POST /api/widget/submit?apiKey=bp_proj_abc123

# Via header
POST /api/widget/submit
X-Api-Key: bp_proj_abc123

Admin API

Admin endpoints require session-based authentication:

1. Call /api/auth/login with credentials
2. Include the session cookie in subsequent requests

# Login
curl -X POST https://bugs.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-password"}' \
  -c cookies.txt

# Use session cookie
curl https://bugs.example.com/api/reports \
  -b cookies.txt

Rate Limiting

Widget submission endpoints are rate limited to prevent abuse:

• Default: 10 requests per minute per IP address
• Configurable in Settings → Security in the Admin Console

Rate limit headers are included in responses:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1234567890

When rate limited, the API returns a 429 Too Many Requests response.

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": [ ... ]  // Optional validation errors
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Origin not allowed or insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Request validation failed
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

Content Types

JSON Requests

curl -X POST https://bugs.example.com/api/widget/submit \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-project-api-key" \
  -d '{"title": "Bug report", ...}'

Multipart Form Data

For requests with file uploads (screenshots):

curl -X POST https://bugs.example.com/api/widget/submit \
  -H "X-Api-Key: your-project-api-key" \
  -F "data={\"title\": \"Bug report\", ...}" \
  -F "media=@screenshot.png"

CORS

The widget API supports Cross-Origin Resource Sharing (CORS) for browser-based requests.

Origin Restrictions

Projects can configure allowed origins in the admin panel. When configured:

• Only requests from allowed origins are accepted
• Subdomains of allowed domains are automatically permitted

Allowed: example.com
Accepts: example.com, www.example.com, app.example.com

Health Check

A health check endpoint is available for monitoring:

GET /health

Returns 200 OK when the server is healthy.