{
  "openapi": "3.0.3",
  "info": {
    "title": "HiScores API",
    "description": "A read-only HTTP API serving pre-generated AI summaries as versioned JSON artifacts. Hosted on GitHub Pages with no server-side computation—all endpoints return static JSON files generated by scheduled pipelines. 404 responses indicate artifacts not yet published.",
    "version": "1.0.0",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://elizaos.github.io",
      "description": "Production deployment"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "paths": {
    "/api/index.json": {
      "get": {
        "summary": "API Index",
        "description": "Discovery endpoint with all available endpoints, capabilities, and metadata. This is the recommended starting point for API consumers - it provides a complete map of all endpoints, valid intervals (day/week/month/lifetime), character system tiers and classes, and available focus areas. Useful for building tools that need to dynamically discover API capabilities.",
        "operationId": "getAPIIndex",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "API discovery metadata with all available endpoints and capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIIndexResponse"
                },
                "example": {
                  "version": "1.0",
                  "baseUrl": "https://elizaos.github.io",
                  "endpoints": {
                    "leaderboard": {
                      "monthly": "https://elizaos.github.io/api/leaderboard-monthly.json",
                      "weekly": "https://elizaos.github.io/api/leaderboard-weekly.json",
                      "lifetime": "https://elizaos.github.io/api/leaderboard-lifetime.json"
                    }
                  },
                  "capabilities": {
                    "intervals": ["day", "week", "month", "lifetime"],
                    "characterSystem": {
                      "tiers": ["beginner", "regular", "active", "veteran", "elite", "legend"],
                      "classes": ["Builder", "Hunter", "Scribe", "Maintainer", "Pathfinder"]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard-monthly.json": {
      "get": {
        "summary": "Monthly Leaderboard",
        "description": "Returns contributors active in the current calendar month (UTC), ordered by contribution level. Shows reputation standing, expertise areas (character classes), skill tiers, specializations (focus areas), achievements, and linked wallet addresses. Updates daily as the month progresses.",
        "operationId": "getMonthlyLeaderboard",
        "tags": ["Leaderboard"],
        "responses": {
          "200": {
            "description": "Contributors ordered by monthly score with character sheets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponse"
                },
                "example": {
                  "version": "1.0",
                  "period": "monthly",
                  "startDate": "2026-01-01",
                  "endDate": "2026-01-31",
                  "totalUsers": 150,
                  "leaderboard": [
                    {
                      "rank": 1,
                      "username": "wtfsayo",
                      "characterClass": "Builder",
                      "tier": "legend",
                      "score": 5642.5,
                      "scoreBreakdown": {
                        "total": 5642.5,
                        "distribution": {
                          "prs": { "score": 4200, "percentage": 74.4 },
                          "issues": { "score": 800, "percentage": 14.2 },
                          "reviews": { "score": 542.5, "percentage": 9.6 },
                          "comments": { "score": 100, "percentage": 1.8 }
                        },
                        "tier": "legend",
                        "percentile": 99.3
                      },
                      "focusAreas": [
                        { "tag": "typescript", "score": 2500, "percentage": 44.3, "rank": 1, "totalInArea": 675 }
                      ],
                      "wallets": { "solana": "ABC123..." }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard-weekly.json": {
      "get": {
        "summary": "Weekly Leaderboard",
        "description": "Returns contributors active in the current week (Sunday→Saturday, UTC), ordered by contribution level. Useful for tracking recent activity and emerging contributors. Updates daily throughout the week.",
        "operationId": "getWeeklyLeaderboard",
        "tags": ["Leaderboard"],
        "responses": {
          "200": {
            "description": "Contributors ordered by weekly score with character sheets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponse"
                },
                "example": {
                  "version": "1.0",
                  "period": "weekly",
                  "startDate": "2026-01-12",
                  "endDate": "2026-01-18",
                  "generatedAt": "2026-01-15T00:00:00.000Z",
                  "totalUsers": 87,
                  "leaderboard": [
                    {
                      "rank": 1,
                      "username": "alice",
                      "characterClass": "Builder",
                      "tier": "active",
                      "score": 1250.5,
                      "scoreBreakdown": {
                        "total": 1250.5,
                        "distribution": {
                          "prs": { "score": 900, "percentage": 72.0 },
                          "issues": { "score": 200, "percentage": 16.0 },
                          "reviews": { "score": 100.5, "percentage": 8.0 },
                          "comments": { "score": 50, "percentage": 4.0 }
                        },
                        "tier": "active",
                        "percentile": 95.4
                      },
                      "focusAreas": [
                        { "tag": "frontend", "score": 600, "percentage": 48.0, "rank": 1, "totalInArea": 125 }
                      ],
                      "wallets": { "solana": "7xKXtg2..." }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboard-lifetime.json": {
      "get": {
        "summary": "Lifetime Leaderboard",
        "description": "Returns all contributors since project inception, ordered by cumulative contribution level. This is the most complete view of contributor expertise and standing within the guild. Use this to understand overall reputation and mastery levels.",
        "operationId": "getLifetimeLeaderboard",
        "tags": ["Leaderboard"],
        "responses": {
          "200": {
            "description": "All contributors ordered by lifetime cumulative score with complete character sheets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponse"
                },
                "example": {
                  "version": "1.0",
                  "period": "lifetime",
                  "startDate": "2024-01-01",
                  "endDate": "2026-01-15",
                  "generatedAt": "2026-01-15T00:00:00.000Z",
                  "totalUsers": 342,
                  "leaderboard": [
                    {
                      "rank": 1,
                      "username": "wtfsayo",
                      "characterClass": "Builder",
                      "tier": "legend",
                      "score": 15842.5,
                      "scoreBreakdown": {
                        "total": 15842.5,
                        "distribution": {
                          "prs": { "score": 11200, "percentage": 70.7 },
                          "issues": { "score": 2800, "percentage": 17.7 },
                          "reviews": { "score": 1542.5, "percentage": 9.7 },
                          "comments": { "score": 300, "percentage": 1.9 }
                        },
                        "tier": "legend",
                        "percentile": 99.7
                      },
                      "focusAreas": [
                        { "tag": "infrastructure", "score": 7500, "percentage": 47.3, "rank": 1, "totalInArea": 2100 },
                        { "tag": "database", "score": 4200, "percentage": 26.5, "rank": 1, "totalInArea": 980 }
                      ],
                      "wallets": { "solana": "ABC123..." }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/overall/{interval}/latest.json": {
      "get": {
        "summary": "Latest Overall Summary",
        "description": "Returns pre-generated AI summary artifact for overall project activity. No server-side computation occurs on request.",
        "operationId": "getLatestOverallSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "AI-generated project summary artifact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "overall",
                  "interval": "week",
                  "date": "2026-01-12",
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "sourceLastUpdated": "2026-01-15T00:53:30.917Z",
                  "contentFormat": "markdown",
                  "content": "High activity week with 127 PRs merged across elizaos/eliza and related repositories. Major focus areas included TypeScript infrastructure improvements, database reliability enhancements, and CI/CD modernization. Top contributors: wtfsayo (45 commits), madjin (32 commits)."
                }
              }
            }
          },
          "404": {
            "description": "Artifact not yet published for this interval",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Not Found",
                  "message": "Summary artifact not yet generated for this interval",
                  "code": 404
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/overall/{interval}/index.json": {
      "get": {
        "summary": "Overall Summary Manifest",
        "description": "Manifest listing all available dated summary artifacts for this interval. Returns array of published snapshots with dates and content hashes for cache validation.",
        "operationId": "getOverallSummaryIndex",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Manifest of available summary artifacts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryIndexResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "overall",
                  "interval": "week",
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "items": [
                    {
                      "date": "2026-01-12",
                      "path": "/api/summaries/overall/week/2026-01-12.json",
                      "contentHash": "3b5f5b9494a3098171038bb9156a8a2fb19dd9ec"
                    },
                    {
                      "date": "2026-01-05",
                      "path": "/api/summaries/overall/week/2026-01-05.json",
                      "contentHash": "f8a2e1c94d5b3a7e2f9c8b1d4a3e2f1c"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No summaries published yet for this interval",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/overall/{interval}/{date}.json": {
      "get": {
        "summary": "Overall Summary by Date",
        "description": "Returns specific dated snapshot of overall project summary artifact",
        "operationId": "getOverallSummaryByDate",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/interval"
          },
          {
            "$ref": "#/components/parameters/date"
          }
        ],
        "responses": {
          "200": {
            "description": "AI-generated project summary for specific date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "overall",
                  "interval": "week",
                  "date": "2026-01-12",
                  "generatedAt": "2026-01-13T02:30:15.000Z",
                  "sourceLastUpdated": "2026-01-13T02:30:15.000Z",
                  "contentFormat": "markdown",
                  "contentHash": "a7c3f9e2d1b4a8c5e9f2d3b1a4c8e5f9",
                  "content": "High-velocity week with 127 PRs merged across 8 core repositories. Infrastructure team delivered critical database optimization reducing query times by 40%. Three new major features shipped: real-time collaboration system, enhanced search with vector embeddings, and automated deployment pipeline. Community engagement up 25% with 42 new contributors making first commits. Security audit completed with zero critical findings."
                }
              }
            }
          },
          "404": {
            "description": "No snapshot exists for this date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/repos/{repoId}/{interval}/latest.json": {
      "get": {
        "summary": "Latest Repository Summary",
        "description": "Returns pre-generated AI summary artifact for repository activity. No server-side computation occurs on request.",
        "operationId": "getLatestRepoSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/repoId"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "AI-generated repository summary artifact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "repository",
                  "interval": "month",
                  "date": "2026-01-01",
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "entity": {
                    "repoId": "elizaos_eliza",
                    "owner": "elizaos",
                    "repo": "eliza"
                  },
                  "contentFormat": "markdown",
                  "content": "January saw major infrastructure improvements in elizaos/eliza with 89 PRs merged. Key themes: SQL plugin overhaul with connection pooling, CI/CD modernization to Opus 4.5, and comprehensive test coverage additions. Top contributors: wtfsayo (database work), madjin (CI improvements)."
                }
              }
            }
          },
          "404": {
            "description": "Repository artifact not yet published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/repos/{repoId}/{interval}/index.json": {
      "get": {
        "summary": "Repository Summary Manifest",
        "description": "Manifest listing all available dated summary artifacts for this repository",
        "operationId": "getRepoSummaryIndex",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/repoId"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Manifest of available repository summary artifacts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryIndexResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "repository",
                  "interval": "week",
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "items": [
                    {
                      "date": "2026-01-12",
                      "path": "/api/summaries/repos/elizaos_eliza/week/2026-01-12.json",
                      "contentHash": "f8a2e1c94d5b3a7e2f9c8b1d4a3e2f1c"
                    },
                    {
                      "date": "2026-01-05",
                      "path": "/api/summaries/repos/elizaos_eliza/week/2026-01-05.json",
                      "contentHash": "d3b2c1a9e5f7a8c4b2d1e3f6a9c5b8d2"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No summaries published yet for this repository",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/contributors/{username}/{interval}/latest.json": {
      "get": {
        "summary": "Latest Contributor Summary",
        "description": "Returns pre-generated AI summary artifact analyzing contributor activity and patterns. No server-side computation occurs on request. Provides contextual insights about contribution focus, collaboration patterns, and recent work.",
        "operationId": "getLatestContributorSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          },
          {
            "name": "interval",
            "in": "path",
            "required": true,
            "description": "Time interval: 'day' (most recent day), 'week' (current week Sunday-Saturday UTC), 'month' (current calendar month). Note: 'lifetime' summaries use different endpoint: /contributors/{username}/lifetime.json",
            "schema": {
              "type": "string",
              "enum": ["day", "week", "month"],
              "example": "month"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "AI-generated narrative analyzing contribution patterns and activity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "contributor",
                  "interval": "month",
                  "date": "2026-01-01",
                  "entity": { "username": "wtfsayo" },
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "contentFormat": "markdown",
                  "contentHash": "3b5f5b9494a3098171038bb9156a8a2fb19dd9ec",
                  "content": "wtfsayo: Focused on enhancing infrastructure stability and database reliability, notably delivering a significant overhaul to the SQL plugin in elizaos/eliza (#6323) that introduced critical pool configurations and error handling. They also modernized the project's CI/CD pipeline by upgrading Claude workflows to Opus 4.5 and enabling automated bot triggers (#6324, #6328). Across 45 commits, they managed extensive modifications to nearly 400 files, demonstrating a high-impact focus on bug fixes and configuration management."
                }
              }
            }
          },
          "404": {
            "description": "Contributor summary not yet published for this interval",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Not Found",
                  "message": "Contributor summary artifact not yet generated",
                  "code": 404
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/contributors/{username}/{interval}/index.json": {
      "get": {
        "summary": "Contributor Summary Manifest",
        "description": "Manifest listing all available dated summary artifacts for this contributor at specified interval",
        "operationId": "getContributorSummaryIndex",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          },
          {
            "$ref": "#/components/parameters/interval"
          }
        ],
        "responses": {
          "200": {
            "description": "Manifest of available contributor summary artifacts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryIndexResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "contributor",
                  "interval": "month",
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "items": [
                    {
                      "date": "2026-01-01",
                      "path": "/api/summaries/contributors/wtfsayo/month/2026-01-01.json",
                      "contentHash": "3b5f5b9494a3098171038bb9156a8a2fb19dd9ec"
                    },
                    {
                      "date": "2025-12-01",
                      "path": "/api/summaries/contributors/wtfsayo/month/2025-12-01.json",
                      "contentHash": "e4c6d7a8b9f1c2d3e5a7b8c9d1f2a3b4"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No summaries published yet for this contributor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/summaries/contributors/{username}/lifetime.json": {
      "get": {
        "summary": "Contributor Lifetime Summary",
        "description": "Returns comprehensive AI-generated narrative of contributor's complete journey. Pre-generated artifact—no server-side computation. Covers contribution trajectory, expertise evolution, collaboration patterns, key achievements, and strategic insights about their role within the guild.",
        "operationId": "getContributorLifetimeSummary",
        "tags": ["Summaries"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          }
        ],
        "responses": {
          "200": {
            "description": "Comprehensive lifetime narrative covering complete contribution history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                },
                "example": {
                  "version": "1.0",
                  "type": "contributor",
                  "interval": "lifetime",
                  "entity": { "username": "wtfsayo" },
                  "generatedAt": "2026-01-15T00:53:30.917Z",
                  "contentFormat": "markdown",
                  "content": "wtfsayo emerged as a foundational architect of the elizaos ecosystem, demonstrating consistent technical leadership from early 2025 through present. Their contributions span database infrastructure, CI/CD automation, and scoring system design. Notable achievements include complete SQL plugin overhaul introducing connection pooling, migration to Opus 4.5 workflows, and design of the guild-based contribution tracking system. Collaboration patterns show strong partnerships with madjin on infrastructure work and shaw on agent framework development."
                }
              }
            }
          },
          "404": {
            "description": "Lifetime summary not yet generated for this contributor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contributors/{username}/profile.json": {
      "get": {
        "summary": "Contributor Profile",
        "description": "Returns complete reputation profile (character sheet) for a contributor. Pre-generated artifact—no server-side computation. Includes tier status, expertise classification (character class), standing across time periods, specialization areas, achievements, and linked wallets. Complete view of contributor's reputation and expertise within the guild.",
        "operationId": "getContributorProfile",
        "tags": ["Profiles"],
        "parameters": [
          {
            "$ref": "#/components/parameters/username"
          }
        ],
        "responses": {
          "200": {
            "description": "Complete character sheet with tier, class, score breakdown, focus areas, and achievements",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserProfileResponse"
                },
                "example": {
                  "version": "1.0",
                  "username": "wtfsayo",
                  "generatedAt": "2026-01-11T05:47:55.389Z",
                  "characterSheet": {
                    "tier": "legend",
                    "characterClass": "Builder",
                    "percentile": 99.93,
                    "rank": {
                      "monthly": 1,
                      "weekly": 2008,
                      "lifetime": 1
                    },
                    "scoreBreakdown": {
                      "total": 24369.65,
                      "distribution": {
                        "prs": { "score": 22191.05, "percentage": 91.06, "label": "Builder" },
                        "issues": { "score": 124.7, "percentage": 0.51, "label": "Hunter" },
                        "reviews": { "score": 1997.5, "percentage": 8.20, "label": "Reviews" },
                        "comments": { "score": 56.39, "percentage": 0.23, "label": "Engagement" }
                      },
                      "tier": "legend",
                      "percentile": 99.93,
                      "characterClass": "Builder"
                    },
                    "focusAreas": [
                      { "tag": "typescript", "score": 6121.5, "percentage": 31.93, "rank": 1, "totalInArea": 678 },
                      { "tag": "core", "score": 2027.5, "percentage": 10.58, "rank": 2, "totalInArea": 305 }
                    ],
                    "achievements": [
                      { "type": "level", "tier": "legend", "earnedAt": "2025-10-27T23:09:12.947Z" },
                      { "type": "pr_master", "tier": "legend", "earnedAt": "2025-10-27T23:09:12.978Z" }
                    ],
                    "wallets": {
                      "ethereum": "0xd257FDc3FD572a82b30D4b17ec43ec09862843B2",
                      "solana": "D2T4FdGvt8KrQqWYYsEKdiTnGmRCnbtsUrNcN1jbJ3Ls"
                    }
                  },
                  "links": {
                    "summaries": {
                      "lifetime": "https://elizaos.github.io/api/summaries/contributors/wtfsayo/lifetime.json",
                      "monthly": "https://elizaos.github.io/api/summaries/contributors/wtfsayo/month/latest.json",
                      "weekly": "https://elizaos.github.io/api/summaries/contributors/wtfsayo/week/latest.json",
                      "daily": "https://elizaos.github.io/api/summaries/contributors/wtfsayo/day/latest.json"
                    },
                    "github": "https://github.com/wtfsayo",
                    "profile": "https://elizaos.github.io/profile/wtfsayo"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Profile not found - contributor may not have any recorded activity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "interval": {
        "name": "interval",
        "in": "path",
        "required": true,
        "description": "Time interval for the summary artifact. 'day' = most recent calendar day with activity. 'week' = current week (Sunday-Saturday UTC). 'month' = current calendar month. Note: For overall/repo summaries, use day/week/month. For contributor summaries, 'lifetime' is also available at /contributors/{username}/lifetime.json",
        "schema": {
          "type": "string",
          "enum": ["day", "week", "month"],
          "example": "week"
        }
      },
      "date": {
        "name": "date",
        "in": "path",
        "required": true,
        "description": "Date in YYYY-MM-DD format",
        "schema": {
          "type": "string",
          "format": "date",
          "example": "2025-01-15"
        }
      },
      "repoId": {
        "name": "repoId",
        "in": "path",
        "required": true,
        "description": "Repository identifier in owner_repo format",
        "schema": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9-]+_[a-zA-Z0-9-_.]+$",
          "example": "elizaos_eliza"
        }
      },
      "username": {
        "name": "username",
        "in": "path",
        "required": true,
        "description": "GitHub username of the contributor. This is case-sensitive and must match exactly as it appears in GitHub.",
        "schema": {
          "type": "string",
          "example": "wtfsayo",
          "pattern": "^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$"
        }
      }
    },
    "schemas": {
      "LeaderboardResponse": {
        "type": "object",
        "required": ["version", "period", "generatedAt", "totalUsers", "leaderboard"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "period": {
            "type": "string",
            "enum": ["monthly", "weekly", "lifetime"]
          },
          "startDate": {
            "type": "string",
            "format": "date",
            "example": "2025-01-01"
          },
          "endDate": {
            "type": "string",
            "format": "date",
            "example": "2025-01-31"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "totalUsers": {
            "type": "integer",
            "example": 150
          },
          "leaderboard": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeaderboardEntry"
            }
          }
        }
      },
      "LeaderboardEntry": {
        "type": "object",
        "required": ["rank", "username", "score"],
        "properties": {
          "rank": {
            "type": "integer",
            "example": 1
          },
          "username": {
            "type": "string",
            "example": "contributor1"
          },
          "avatarUrl": {
            "type": "string",
            "format": "uri"
          },
          "score": {
            "type": "number",
            "example": 1250
          },
          "prScore": {
            "type": "number",
            "example": 800
          },
          "issueScore": {
            "type": "number",
            "example": 200
          },
          "reviewScore": {
            "type": "number",
            "example": 150
          },
          "commentScore": {
            "type": "number",
            "example": 100
          },
          "wallets": {
            "type": "object",
            "properties": {
              "solana": {
                "type": "string"
              },
              "ethereum": {
                "type": "string"
              }
            }
          }
        }
      },
      "SummaryResponse": {
        "type": "object",
        "required": ["version", "type", "interval", "date", "generatedAt", "content"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "type": {
            "type": "string",
            "enum": ["overall", "repository", "contributor"]
          },
          "interval": {
            "type": "string",
            "enum": ["day", "week", "month"]
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2025-01-15"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "sourceLastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "contentHash": {
            "type": "string",
            "description": "SHA-256 hash of the content for cache validation"
          },
          "content": {
            "type": "string",
            "description": "Markdown-formatted summary content"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "entityId": {
                "type": "string"
              },
              "repoId": {
                "type": "string"
              },
              "owner": {
                "type": "string"
              },
              "repo": {
                "type": "string"
              },
              "username": {
                "type": "string"
              }
            }
          }
        }
      },
      "SummaryIndexResponse": {
        "type": "object",
        "required": ["version", "type", "interval", "generatedAt", "items"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "type": {
            "type": "string"
          },
          "interval": {
            "type": "string",
            "enum": ["day", "week", "month"]
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SummaryIndexItem"
            }
          }
        }
      },
      "SummaryIndexItem": {
        "type": "object",
        "required": ["date", "path"],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "sourceLastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "contentHash": {
            "type": "string"
          },
          "path": {
            "type": "string",
            "description": "Relative path to the summary file"
          }
        }
      },
      "UserProfileResponse": {
        "type": "object",
        "required": ["version", "username", "generatedAt", "characterSheet", "links"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "username": {
            "type": "string",
            "example": "contributor1"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "characterSheet": {
            "type": "object",
            "required": ["tier", "characterClass", "percentile", "rank", "scoreBreakdown", "focusAreas", "wallets"],
            "properties": {
              "tier": {
                "type": "string",
                "enum": ["beginner", "regular", "active", "veteran", "elite", "legend"],
                "example": "elite"
              },
              "characterClass": {
                "type": "string",
                "description": "Derived class (Author, Reviewer, Maintainer, etc.)",
                "example": "Maintainer"
              },
              "percentile": {
                "type": "number",
                "description": "Percentile ranking among all contributors",
                "example": 95.3
              },
              "rank": {
                "type": "object",
                "required": ["monthly", "weekly", "lifetime"],
                "properties": {
                  "monthly": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Rank in current month (null if no activity)",
                    "example": 12
                  },
                  "weekly": {
                    "type": "integer",
                    "nullable": true,
                    "description": "Rank in current week (null if no activity)",
                    "example": 8
                  },
                  "lifetime": {
                    "type": "integer",
                    "nullable": true,
                    "description": "All-time rank (null if no activity)",
                    "example": 15
                  }
                }
              },
              "scoreBreakdown": {
                "type": "object",
                "description": "Detailed score breakdown by contribution type",
                "properties": {
                  "total": { "type": "number", "example": 1250 },
                  "prScore": { "type": "number", "example": 800 },
                  "issueScore": { "type": "number", "example": 200 },
                  "reviewScore": { "type": "number", "example": 150 },
                  "commentScore": { "type": "number", "example": 100 }
                }
              },
              "focusAreas": {
                "type": "array",
                "description": "Top expertise areas with rankings",
                "items": {
                  "type": "object",
                  "properties": {
                    "area": { "type": "string", "example": "core" },
                    "count": { "type": "integer", "example": 45 },
                    "rank": { "type": "integer", "example": 3 }
                  }
                }
              },
              "achievements": {
                "type": "array",
                "description": "Earned badges and achievements",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "example": "first-pr" },
                    "name": { "type": "string", "example": "First PR" },
                    "description": { "type": "string", "example": "Merged first pull request" },
                    "earnedAt": { "type": "string", "format": "date-time" }
                  }
                }
              },
              "profile": {
                "type": "object",
                "description": "GitHub profile information",
                "properties": {
                  "avatarUrl": { "type": "string", "format": "uri" },
                  "name": { "type": "string", "example": "John Doe" },
                  "bio": { "type": "string" },
                  "location": { "type": "string" },
                  "twitter": { "type": "string" }
                }
              },
              "wallets": {
                "type": "object",
                "description": "Cryptocurrency wallet addresses",
                "properties": {
                  "solana": { "type": "string" },
                  "ethereum": { "type": "string" }
                }
              }
            }
          },
          "links": {
            "type": "object",
            "required": ["summaries", "github", "profile"],
            "properties": {
              "summaries": {
                "type": "object",
                "required": ["lifetime", "monthly", "weekly", "daily"],
                "properties": {
                  "lifetime": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/lifetime.json"
                  },
                  "monthly": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/month/latest.json"
                  },
                  "weekly": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/week/latest.json"
                  },
                  "daily": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://elizaos.github.io/api/summaries/contributors/contributor1/day/latest.json"
                  }
                }
              },
              "github": {
                "type": "string",
                "format": "uri",
                "example": "https://github.com/contributor1"
              },
              "profile": {
                "type": "string",
                "format": "uri",
                "example": "https://elizaos.github.io/profile/contributor1"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": {
            "type": "string",
            "example": "Not Found"
          },
          "message": {
            "type": "string",
            "example": "Artifact not yet published"
          },
          "code": {
            "type": "integer",
            "example": 404
          }
        }
      },
      "APIIndexResponse": {
        "type": "object",
        "required": ["version", "baseUrl", "documentation", "openapi", "endpoints", "capabilities"],
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "baseUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://elizaos.github.io"
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "example": "https://elizaos.github.io/api"
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "example": "https://elizaos.github.io/openapi.json"
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "leaderboard": {
                "type": "object",
                "properties": {
                  "monthly": { "type": "string", "format": "uri" },
                  "weekly": { "type": "string", "format": "uri" },
                  "lifetime": { "type": "string", "format": "uri" }
                }
              },
              "profiles": {
                "type": "object",
                "properties": {
                  "pattern": { "type": "string" },
                  "example": { "type": "string", "format": "uri" }
                }
              },
              "summaries": {
                "type": "object",
                "properties": {
                  "overall": {
                    "type": "object",
                    "properties": {
                      "pattern": { "type": "string" },
                      "intervals": { "type": "array", "items": { "type": "string" } }
                    }
                  },
                  "contributors": {
                    "type": "object",
                    "properties": {
                      "pattern": { "type": "string" },
                      "intervals": { "type": "array", "items": { "type": "string" } }
                    }
                  }
                }
              }
            }
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "search": {
                "type": "object",
                "properties": {
                  "byUsername": { "type": "boolean" },
                  "byRank": { "type": "boolean" },
                  "byTier": { "type": "boolean" },
                  "byFocusArea": { "type": "boolean" }
                }
              },
              "intervals": {
                "type": "array",
                "items": { "type": "string" },
                "example": ["day", "week", "month", "lifetime"]
              },
              "characterSystem": {
                "type": "object",
                "properties": {
                  "tiers": {
                    "type": "array",
                    "items": { "type": "string" }
                  },
                  "classes": {
                    "type": "array",
                    "items": { "type": "string" }
                  },
                  "focusAreas": {
                    "type": "array",
                    "items": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "API discovery and metadata endpoints"
    },
    {
      "name": "Leaderboard",
      "description": "Contributor ranking endpoints"
    },
    {
      "name": "Profiles",
      "description": "Individual contributor character sheets"
    },
    {
      "name": "Summaries",
      "description": "AI-generated project summaries"
    }
  ]
}