🚀 gh-proxy API Documentation

gh-proxy is a GitHub API proxy that provides rate limiting, caching, and token pooling for GitHub API requests.

⚠️ API Key Required: All API requests require a valid API key. Contact an administrator to get one.

📋 Quick Start

Base URL

https://gh-proxy.hackclub.com

Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key_here" https://gh-proxy.hackclub.com/gh/user

🔗 Available Endpoints

GET /gh/{path}

Description: Proxy any GitHub REST API endpoint

Example:

# Get current user
curl -H "X-API-Key: your_key" https://gh-proxy.hackclub.com/gh/user

# Get repository information
curl -H "X-API-Key: your_key" https://gh-proxy.hackclub.com/gh/repos/octocat/Hello-World

# List user repositories
curl -H "X-API-Key: your_key" https://gh-proxy.hackclub.com/gh/users/octocat/repos

# Search repositories
curl -H "X-API-Key: your_key" "https://gh-proxy.hackclub.com/gh/search/repositories?q=javascript"

POST /gh/graphql

Description: Proxy GitHub GraphQL API

Content-Type: application/json

Example:

# GraphQL query
curl -X POST \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { viewer { login name } }"}' \
  https://gh-proxy.hackclub.com/gh/graphql

⚡ Rate Limiting

Each API key has its own rate limit (configurable per key, default: 10 requests/second).

Rate Limit Exceeded: Returns 429 Too Many Requests when limit is exceeded.

🗄️ Caching

Responses are automatically cached to improve performance:

Cached: GET and HEAD requests with successful responses (200 OK)
Not Cached: POST, PUT, DELETE requests
Cache Headers: Check X-Gh-Proxy-Cache header for hit/miss status
Cache Duration: Configurable (default: 5 minutes)

Cache Hit: X-Gh-Proxy-Cache: hit means the response came from cache

Cache Miss: X-Gh-Proxy-Cache: miss means a fresh request was made to GitHub

📊 Response Headers

The proxy adds helpful debug headers to responses:

X-Gh-Proxy-Cache: hit/miss - Whether response came from cache
X-Gh-Proxy-Category: core/search/graphql - API category used
X-Gh-Proxy-Client: Your API key identifier
X-Gh-Proxy-Donor: GitHub user who donated the token used (when applicable)

🔧 JavaScript/Node.js Examples

Using fetch()

const response = await fetch('https://gh-proxy.hackclub.com/gh/user', {
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
});
const user = await response.json();
console.log(user);

Using axios

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://gh-proxy.hackclub.com/gh',
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
});

// Get user info
const user = await api.get('/user');

// GraphQL query
const graphql = await api.post('/graphql', {
  query: 'query { viewer { login repositories(first: 10) { nodes { name } } } }'
});

🐍 Python Example

import requests

headers = {'X-API-Key': 'your_api_key_here'}

# REST API
response = requests.get('https://gh-proxy.hackclub.com/gh/user', headers=headers)
user = response.json()

# GraphQL
graphql_query = {
    "query": "query { viewer { login name } }"
}
response = requests.post('https://gh-proxy.hackclub.com/gh/graphql', 
                        headers=headers, 
                        json=graphql_query)
data = response.json()

⚠️ Error Responses

401 Unauthorized: Missing or invalid API key
403 Forbidden: API key disabled or insufficient permissions
413 Request Entity Too Large: Request body too large (max 1MB)
429 Too Many Requests: Rate limit exceeded

💡 Tips & Best Practices

Cache Efficiently: Use GET requests when possible to benefit from caching
Handle Rate Limits: Implement exponential backoff for 429 responses
Check Headers: Use debug headers to monitor cache performance
Batch Requests: Use GraphQL for complex queries to reduce request count
Monitor Usage: Check the admin panel for usage statistics

📞 Support

For API keys or technical support, contact your system administrator.

← Back to Home Admin Panel