Skip to main content
This is the complete reference for the Pear API. Every endpoint is documented with its parameters, request/response schemas, and example payloads.

​
Base URL

All API requests should be made to: 
http://localhost:8000

​
Authentication

All endpoints (except / and /health) require an API key. Pass it using either method: 
# Bearer token (recommended)
Authorization: Bearer mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# API key header
X-API-Key: mk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
See the Authentication guide for details on key management and scopes.

​
Response format

All successful responses return JSON. Paginated endpoints use a consistent envelope: 
{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6...",
  "has_more": true,
  "total_count": 11507
}
Non-paginated endpoints return the resource directly or as an array.

​
Error responses

Errors return a JSON object with error and message fields: 
{
  "error": "not_found",
  "message": "The requested resource was not found."
}

​
HTTP status codes

CodeDescription
200Success.
201Resource created successfully.
204Success with no response body (e.g., after deletion).
401Unauthorized. Missing or invalid API key.
403Forbidden. The API key lacks the required scope.
404Not found. The requested resource does not exist.
422Validation error. The request body or parameters are invalid.
429Rate limit exceeded. Wait and retry.
500Internal server error. Contact support if this persists.

​
Rate limiting

Every response includes rate limit headers:
HeaderDescription
X-RateLimit-LimitMaximum requests per minute for your plan.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp when the window resets.
See the Rate Limits guide for per-plan limits and best practices.

​
Pagination

List endpoints use cursor-based pagination. Pass cursor and limit query parameters to navigate results. See the Pagination guide for details.

​
Endpoints overview

​
Events

MethodEndpointDescription
GET/api/eventsList unified events
GET/api/events/categoriesList all categories with counts
GET/api/events/{slug}Get event by slug with markets
GET/api/events/{slug}/marketsGet markets for an event

​
Markets

MethodEndpointDescription
GET/api/marketsList venue markets
GET/api/markets/{venue}/{market_id}Get a specific market
MethodEndpointDescription
GET/api/searchSearch events by keyword

​
Comparisons

MethodEndpointDescription
GET/api/comparisonsList cross-platform comparisons
GET/api/comparisons/{comparison_id}Get comparison with market data

​
Account

MethodEndpointDescription
GET/api/users/meGet your profile
GET/api/users/me/usageGet usage statistics
GET/api/users/me/usage/logsGet recent request logs
GET/api/users/me/rate-limitGet rate limit status
GET/api/keysList your API keys
POST/api/keysCreate a new API key
DELETE/api/keys/{key_id}Revoke an API key