API Documentation

Public REST API for accessing developer profiles, scorecards, and arena rankings.

Base URL

https://github.gg

Authentication

All API endpoints require authentication using an API key. Include your key in the request headers:

# Option 1: Authorization header

Authorization: Bearer gg_your_api_key_here

# Option 2: X-API-Key header

X-API-Key: gg_your_api_key_here

Getting an API Key

Note: Only public GitHub profiles and repositories are accessible via the API. Private repository scorecards require authentication via the web interface.

Response Format

All responses are JSON. Successful responses return HTTP 200 with the data. Errors return appropriate HTTP status codes with an error message.

Success Response (200):

{ "data": { ... } }

Error Responses:

401 - Missing or invalid API key

403 - Insufficient permissions (wrong scope)

404 - Resource not found

429 - Rate limit exceeded

500 - Internal server error

Caching

Responses include cache headers. Profile and scorecard data is cached for 5 minutes with stale-while-revalidate for 10 minutes. The stale field indicates if the data is older than 7 days.

Endpoints

GET/api/v1/profiles/:username

Get a developer profile by GitHub username

Parameters

Name	Type	Description
username	path	GitHub username

Example Request

curl -H "Authorization: Bearer gg_your_key" https://github.gg/api/v1/profiles/torvalds

Example Response

{
  "username": "torvalds",
  "profile": {
    "summary": "Creator of Linux and Git...",
    "skillAssessment": [...],
    "techStack": [...],
    "developerArchetype": "Domain Specialist",
    "profileConfidence": 95
  },
  "cached": true,
  "stale": false,
  "lastUpdated": "2024-01-15T10:30:00Z"
}

GET/api/v1/profiles/search

Search developer profiles with filters

Parameters

Name	Type	Description
skills	query	Comma-separated skills (e.g., "React,TypeScript")
archetypes	query	Comma-separated types (e.g., "Production Builder")
minConfidence	query	Minimum profile confidence (0-100)
q	query	Free text search
limit	query	Max results (default 50, max 100)
offset	query	Pagination offset

Example Request

curl -H "Authorization: Bearer gg_your_key" https://github.gg/api/v1/profiles/search?skills=React,TypeScript&minConfidence=70&limit=10

Example Response

{
  "results": [
    {
      "username": "developer1",
      "summary": "Full-stack engineer...",
      "archetype": "Production Builder",
      "confidence": 85,
      "topSkills": [
        { "name": "React", "score": 9 },
        { "name": "TypeScript", "score": 8 }
      ]
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0,
  "hasMore": false
}

GET/api/v1/scorecards/:owner/:repo

Get repository scorecard analysis

Parameters

Name	Type	Description
owner	path	Repository owner
repo	path	Repository name
version	query	Specific version (optional)

Example Request

curl -H "Authorization: Bearer gg_your_key" https://github.gg/api/v1/scorecards/facebook/react

Example Response

{
  "owner": "facebook",
  "repo": "react",
  "scorecard": {
    "overallScore": 92,
    "metrics": [
      { "name": "Code Quality", "score": 95, "reason": "..." },
      { "name": "Documentation", "score": 90, "reason": "..." }
    ],
    "markdown": "## Analysis\n..."
  },
  "version": 3,
  "cached": true,
  "stale": false,
  "lastUpdated": "2024-01-15T10:30:00Z",
  "ref": "main"
}

GET/api/v1/arena/leaderboard

Get arena rankings leaderboard

Parameters

Name	Type	Description
limit	query	Max results (default 50, max 100)
offset	query	Pagination offset
tier	query	Filter by tier (optional)

Example Request

curl -H "Authorization: Bearer gg_your_key" https://github.gg/api/v1/arena/leaderboard?limit=10

Example Response

{
  "leaderboard": [
    {
      "rank": 1,
      "username": "developer1",
      "eloRating": 1850,
      "tier": "Diamond",
      "wins": 45,
      "losses": 12,
      "winRate": 78.9,
      "totalBattles": 57,
      "winStreak": 5
    }
  ],
  "limit": 10,
  "offset": 0
}

GET/api/v1/arena/rankings/:username

Get arena ranking for a specific user

Parameters

Name	Type	Description
username	path	GitHub username

Example Request

curl -H "Authorization: Bearer gg_your_key" https://github.gg/api/v1/arena/rankings/torvalds

Example Response

{
  "username": "torvalds",
  "ranking": {
    "rank": 42,
    "eloRating": 1650,
    "tier": "Platinum",
    "wins": 28,
    "losses": 15,
    "winRate": 65.1,
    "totalBattles": 43,
    "winStreak": 2
  }
}

Developer Archetypes

Profiles are classified into one of these archetypes based on their GitHub activity:

Production Builder

Full-Stack Generalist

Domain Specialist

Research & Innovation

Open Source Contributor

Early Career Explorer

Rate Limits

API requests are rate limited to prevent abuse. Current limits:

• 100 requests per minute per IP address
• 1000 requests per hour per IP address

Need Help?

For questions, feature requests, or enterprise access, contact us at [email protected]