Base URL
All API endpoints are relative to your deployment base URL:Request Format
All requests use standard HTTP methods and accept parameters via:- GET requests: Query parameters in the URL
- POST requests: JSON body (where applicable)
Response Format
All API responses return JSON with the following structure:Error Handling
The API uses standard HTTP status codes:| Status Code | Description |
|---|---|
200 | Success |
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Authentication required |
404 | Not Found - Repository or user doesn’t exist |
429 | Rate Limited - GitHub API rate limit exceeded |
500 | Internal Server Error |
Rate Limiting
The API respects GitHub’s rate limits:- Authenticated requests: 5,000 requests/hour
- Unauthenticated requests: 60 requests/hour
resetAt timestamp:
Caching
Public repository data is cached for 24 hours. Cached responses include"cached": true in the response.
Private repository data is never cached when accessed with an accessToken.
Quick Reference
Repository Endpoints
| Endpoint | Method | Description | Auth Required |
|---|---|---|---|
/api/wrapped | GET | Generate repository year-in-review | Optional* |
/api/validate | GET | Validate repository exists | Optional* |
User Endpoints
| Endpoint | Method | Description | Auth Required |
|---|---|---|---|
/api/wrapped/user | GET | Generate user year-in-review | Optional* |
/api/performance | GET | Get authenticated user performance | Yes |
/api/summary | GET | Get authenticated user monthly summary | Yes |
/api/user/repos | GET | List authenticated user repositories | Yes |
Authentication Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/auth/* | GET/POST | Better Auth OAuth handlers |
Example Request
Next Steps
Authentication
Learn about GitHub OAuth integration
Repository Wrapped
Generate repository analytics
User Wrapped
Generate user activity analytics
Data Models
TypeScript interfaces and data structures