← Back to Home OpenAPI Spec llms.txt Admin Panel

🚀 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) over a one-second window.

Rate Limit Exceeded: Returns 429 Too Many Requests when limit is exceeded, with a Retry-After header.

Every /gh/ response reports your live quota so you can self-throttle without waiting for a 429:

GitHub's own upstream quota is passed through unchanged as X-RateLimit-*. Those headers describe GitHub's limit on the donated token that served your request; the RateLimit-* headers above describe this proxy's limit on your key.

curl -sD- -o /dev/null -H "X-API-Key: your_key" https://gh-proxy.hackclub.com/gh/rate_limit

RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 1
RateLimit-Policy: "default";q=10;w=1
RateLimit: "default";r=9;t=1

🗄️ Caching

Responses are automatically cached to improve performance:

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:

🔧 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

Every error this proxy generates is JSON, never an HTML page. The envelope is stable:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "hint": "This key allows 10 requests/second; retry after 1 second(s) and back off exponentially",
    "documentation_url": "https://gh-proxy.hackclub.com/docs"
  }
}

Branch on error.code — it is stable. message and hint are for humans and logs. 404 and 405 responses also carry an error.links array pointing at the entry points of this service.

Status codes and error codes

Any other status on a /gh/ request is GitHub's own response, forwarded verbatim. A 404 from /gh/repos/does/not-exist is GitHub's 404, with GitHub's body.

🤖 For Agents

💡 Tips & Best Practices

📞 Support

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

← Back to Home OpenAPI Spec llms.txt Admin Panel