{"name":"PinchBench API","version":"1.0.0","description":"Benchmarking leaderboard API for AI/LLM models. Submit benchmark results, view leaderboards, and compare model performance across providers.","openapi_spec":"https://api.pinchbench.com/openapi.json","documentation":"https://pinchbench.com","endpoints":[{"method":"POST","path":"/api/results","summary":"Submit benchmark results","description":"Submit benchmark results for an AI model run. Requires authentication. If a submission with the same ID already exists, returns the existing ranking without creating a duplicate.","tags":["Submissions"],"auth":"token","params":[]},{"method":"POST","path":"/api/register","summary":"Register a new API token","description":"Creates a new API token and returns it along with a claim URL for GitHub verification. The token is prefixed with pb_live_ and should be stored securely.","tags":["Authentication"],"auth":"none","params":[]},{"method":"GET","path":"/api/leaderboard","summary":"Get aggregated leaderboard","description":"Returns the best scores grouped by model. Each entry includes best and average scores, execution times, costs, and submission counts.","tags":["Leaderboard"],"auth":"none","params":[{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version ID (or 'latest')"},{"name":"verified","in":"query","type":"string","required":false,"description":"Set to 'true' to only include submissions from claimed tokens","enum":["true","false"]},{"name":"official","in":"query","type":"string","required":false,"description":"Set to 'true' to only include official submissions","enum":["true","false"]},{"name":"provider","in":"query","type":"string","required":false,"description":"Filter by provider name"},{"name":"limit","in":"query","type":"integer","required":false,"description":"Max results to return","default":50}]},{"method":"GET","path":"/api/models","summary":"List all models","description":"Returns all models with submission counts, best scores, and latest submission dates. Useful for building filter dropdowns or exploring available models.","tags":["Leaderboard"],"auth":"none","params":[{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version ID (or 'latest')"},{"name":"verified","in":"query","type":"string","required":false,"description":"Set to 'true' for claimed tokens only","enum":["true","false"]}]},{"method":"GET","path":"/api/stats","summary":"Get aggregate statistics","description":"Returns high-level statistics: total submissions, total models, verified submissions, recent activity, and the current top model.","tags":["Leaderboard"],"auth":"none","params":[{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version ID (or 'latest')"}]},{"method":"GET","path":"/api/submissions","summary":"List submissions with filters","description":"Returns a paginated list of benchmark submissions. Supports filtering by model, provider, verification status, and benchmark version.","tags":["Submissions"],"auth":"none","params":[{"name":"model","in":"query","type":"string","required":false,"description":"Filter by model name"},{"name":"provider","in":"query","type":"string","required":false,"description":"Filter by provider"},{"name":"verified","in":"query","type":"string","required":false,"description":"Set to 'true' for claimed tokens only","enum":["true","false"]},{"name":"official","in":"query","type":"string","required":false,"description":"Set to 'true' for official runs only","enum":["true","false"]},{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version ID (or 'latest')"},{"name":"sort","in":"query","type":"string","required":false,"description":"Sort order","default":"score","enum":["score","recent","oldest"]},{"name":"limit","in":"query","type":"integer","required":false,"description":"Max results (1-100)","default":20},{"name":"offset","in":"query","type":"integer","required":false,"description":"Pagination offset","default":0}]},{"method":"GET","path":"/api/submissions/:id","summary":"Get submission details","description":"Returns full details for a single submission including task breakdown, usage summary, metadata, rank, and percentile.","tags":["Submissions"],"auth":"none","params":[{"name":"id","in":"path","type":"string","required":true,"description":"Submission UUID"}]},{"method":"GET","path":"/api/model-submissions","summary":"Get all submissions for a specific model","description":"Returns a lightweight list of all submissions for a given model ordered by score. Includes an is_best flag marking the leaderboard entry.","tags":["Submissions"],"auth":"none","params":[{"name":"model","in":"query","type":"string","required":true,"description":"Model name (e.g. google/gemini-2.5-pro)"},{"name":"verified","in":"query","type":"string","required":false,"description":"Set to 'true' for claimed tokens only","enum":["true","false"]},{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version"}]},{"method":"GET","path":"/api/me/submissions","summary":"Get your submissions","description":"Returns submissions for the authenticated user's token. Requires X-PinchBench-Token header.","tags":["Submissions"],"auth":"token","params":[{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version"},{"name":"limit","in":"query","type":"integer","required":false,"description":"Max results (1-100)","default":20},{"name":"offset","in":"query","type":"integer","required":false,"description":"Pagination offset","default":0}]},{"method":"GET","path":"/api/benchmark_versions","summary":"List all benchmark versions","description":"Returns all non-hidden benchmark versions sorted by semver (descending). Includes submission counts, release notes, and whether each version is current.","tags":["Benchmark Versions"],"auth":"none","params":[]},{"method":"GET","path":"/api/benchmark_versions/latest","summary":"Get the current benchmark version","description":"Returns the benchmark version marked as current, with its submission count and release details.","tags":["Benchmark Versions"],"auth":"none","params":[]},{"method":"GET","path":"/api/providers","summary":"List all providers","description":"Returns a list of all unique provider names from submissions.","tags":["Providers"],"auth":"none","params":[{"name":"verified","in":"query","type":"string","required":false,"description":"Set to 'true' for claimed tokens only","enum":["true","false"]}]},{"method":"GET","path":"/api/providers/:provider/models","summary":"List models for a provider with stats","description":"Returns models available from a specific provider along with submission counts, best/average scores, costs, and execution times.","tags":["Providers"],"auth":"none","params":[{"name":"provider","in":"path","type":"string","required":true,"description":"Provider name"},{"name":"verified","in":"query","type":"string","required":false,"description":"Set to 'true' for claimed tokens only","enum":["true","false"]},{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version"}]},{"method":"GET","path":"/api/claim/github","summary":"Initiate GitHub OAuth claim flow","description":"Validates a claim code and redirects the user to GitHub OAuth for token verification. The claim code is used as the OAuth state parameter.","tags":["Authentication"],"auth":"none","params":[{"name":"claim_code","in":"query","type":"string","required":true,"description":"Claim code from token registration"}]},{"method":"GET","path":"/api/claim/github/callback","summary":"GitHub OAuth callback","description":"GitHub redirects here after user authorization. Exchanges the code for a token, fetches the GitHub user, and marks the API token as claimed. This is a browser redirect endpoint, not intended for direct API consumption.","tags":["Authentication"],"auth":"none","params":[{"name":"code","in":"query","type":"string","required":true,"description":"GitHub OAuth authorization code"},{"name":"state","in":"query","type":"string","required":true,"description":"Claim code (CSRF state)"}]},{"method":"POST","path":"/api/claim/refresh","summary":"Refresh an expired claim code","description":"Generates a new claim code and URL for a token that hasn't been claimed yet. Requires authentication with the token to be refreshed.","tags":["Authentication"],"auth":"token","params":[]},{"method":"GET","path":"/api/users/:github_username/submissions","summary":"Public submissions for a GitHub user","description":"Returns all submissions from tokens claimed by the given GitHub user. No authentication required — this is a public profile view.","tags":["Users"],"auth":"none","params":[{"name":"github_username","in":"path","type":"string","required":true,"description":"GitHub username (case-insensitive)"},{"name":"version","in":"query","type":"string","required":false,"description":"Filter by benchmark version"},{"name":"sort","in":"query","type":"string","required":false,"description":"Sort order","default":"score","enum":["score","recent","oldest"]},{"name":"limit","in":"query","type":"integer","required":false,"description":"Max results (1-100)","default":20},{"name":"offset","in":"query","type":"integer","required":false,"description":"Pagination offset","default":0}]}],"_meta":{"total_endpoints":17,"generated_at":"2026-06-01T00:16:10.409Z","content_types":["application/json","text/markdown"]}}