API Overview

BugPin provides a REST API for widget integration and programmatic access.

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/webhooks	Webhook configuration
/api/integrations	Third-party integrations

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 via RATE_LIMIT_MAX and RATE_LIMIT_WINDOW environment variables

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-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-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.