Skip to main content

​
Introduction

The Better Hub API provides programmatic access to GitHub data with enhanced features like AI-powered chat, semantic search, and workflow management. The API is built on Next.js App Router and uses session-based authentication.

​
Base URL

https://www.better-hub.com/api
For local development: 
http://localhost:3000/api

​
Response Format

All API responses are returned in JSON format. Successful responses return the requested data directly, while errors follow this structure:
​
error
string
Human-readable error message
​
details
object
Additional error details (for validation errors)

​
Example Success Response

{
  "login": "octocat",
  "name": "The Octocat",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "bio": "GitHub mascot",
  "public_repos": 8,
  "followers": 1000,
  "following": 0
}

​
Example Error Response

{
  "error": "Unauthorized"
}

​
Rate Limiting

Better Hub implements rate limiting on sensitive endpoints:
  • PAT Sign-in: 5 requests per minute per IP
  • AI endpoints: Subject to credit limits and usage tracking
  • GitHub API: Inherits GitHub’s rate limits based on your authentication
Rate limit information is not currently exposed in response headers, but failed requests will return a 429 Too Many Requests status.
API rate limits are separate from GitHub’s rate limits. GitHub API calls made through Better Hub use your GitHub OAuth token and count against your GitHub rate limit.

​
API Categories

The Better Hub API is organized into the following categories:

Authentication

Session-based auth with GitHub OAuth and Personal Access Tokens

User Management

User profiles, settings, and preferences
  • GET /api/user-profile
  • GET /api/user-settings
  • PATCH /api/user-settings
  • GET /api/user-scopes

GitHub Data

Search and retrieve GitHub repositories, issues, PRs, and users
  • GET /api/search-repos
  • GET /api/search-issues
  • GET /api/search-prs
  • GET /api/search-users
  • GET /api/search-code
  • GET /api/user-repos
  • GET /api/org-repos

Repository Files

Access repository files and code
  • GET /api/file-content
  • GET /api/repo-files
  • GET /api/highlight-code

Workflows & Actions

GitHub Actions workflow runs and logs
  • GET /api/workflow-runs
  • GET /api/job-logs
  • GET /api/check-status

AI Features

AI-powered chat, commit messages, and code assistance
  • POST /api/ai/ghost - AI chat with GitHub context
  • POST /api/ai/commit-message - Generate commit messages
  • POST /api/ai/command - Execute AI commands
  • GET /api/ai/chat-history - Retrieve chat history

Billing & Credits

Credit balance and spending limits
  • GET /api/billing/balance
  • GET /api/billing/spending-limit
  • PATCH /api/billing/spending-limit
  • POST /api/billing/welcome

Utilities

Helper endpoints for images, merge conflicts, and uploads
  • GET /api/github-image
  • GET /api/merge-conflicts
  • POST /api/upload
  • GET /api/rate-limit

​
Authentication Required

Most API endpoints require authentication. See the Authentication guide for details on:
  • GitHub OAuth flow
  • Personal Access Token (PAT) sign-in
  • Session management
  • Using sessions in API requests
Unauthenticated requests will receive a 401 Unauthorized response.

​
CORS & Security

The API is configured with trusted origins:
  • https://www.better-hub.com (production)
  • https://beta.better-hub.com (beta environment)
  • https://better-hub-*-better-auth.vercel.app (Vercel previews)
Cross-origin requests from other domains will be rejected.

​
Common Query Parameters

Many search and list endpoints support these query parameters:
​
page
number
default:"1"
Page number for pagination
​
per_page
number
default:"30"
Number of results per page (max: 100)
​
q
string
Search query string
​
sort
string
Sort field (varies by endpoint)
​
order
string
Sort order: asc or desc

​
Next Steps

Authentication

Learn how to authenticate API requests

GitHub Integration

Explore GitHub data endpoints

AI Features

Use AI-powered features

Example Apps

Build with the Better Hub API