{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenFunnel Bench Public API",
    "version": "0.1.0",
    "description": "Read-only public API serving the same benchmark data the website renders. No authentication required. CORS is open.",
    "license": {
      "name": "CC-BY-4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "contact": {
      "name": "OpenFunnel",
      "url": "https://benchmarks.openfunnel.dev"
    }
  },
  "servers": [
    {
      "url": "https://benchmarks.openfunnel.dev"
    }
  ],
  "externalDocs": {
    "description": "OpenFunnel Bench documentation, methodology, and metric definitions.",
    "url": "https://benchmarks.openfunnel.dev"
  },
  "tags": [
    {
      "name": "leaderboards",
      "description": "Read-only endpoints exposing benchmark leaderboard data. Identical to what the website renders.",
      "externalDocs": {
        "description": "Methodology and metric definitions.",
        "url": "https://benchmarks.openfunnel.dev/leaderboards/work-email-enrichment#methodology"
      }
    }
  ],
  "x-mcp-servers": [
    {
      "name": "openfunnel",
      "url": "https://mcp.openfunnel.dev/mcp",
      "transport": "http",
      "protocol_version": "2025-03-26",
      "description": "OpenFunnel MCP server — connect Claude, ChatGPT, Cursor and other MCP clients to OpenFunnel data via tools, prompts, and resources. OAuth 2.1 with dynamic client registration.",
      "documentation": "https://docs.openfunnel.dev/mcp-reference",
      "capabilities": {
        "tools": true,
        "prompts": true,
        "resources": true,
        "tasks": true
      },
      "auth": {
        "type": "oauth2",
        "flow": "authorization_code",
        "pkce": "S256",
        "scopes": [
          "mcp"
        ],
        "dynamic_registration": true,
        "authorization_endpoint": "https://mcp.openfunnel.dev/oauth/authorize",
        "token_endpoint": "https://mcp.openfunnel.dev/oauth/token",
        "registration_endpoint": "https://mcp.openfunnel.dev/oauth/register",
        "metadata_url": "https://mcp.openfunnel.dev/.well-known/oauth-authorization-server"
      }
    }
  ],
  "paths": {
    "/api/leaderboards": {
      "get": {
        "tags": [
          "leaderboards"
        ],
        "summary": "List all benchmarks",
        "description": "Returns the index of all published benchmarks with summary winners and links to each detail endpoint. Safe to call without authentication.",
        "operationId": "listLeaderboards",
        "responses": {
          "200": {
            "description": "Index of leaderboards.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardIndex"
                },
                "example": {
                  "site": {
                    "name": "OpenFunnel Bench",
                    "url": "https://benchmarks.openfunnel.dev",
                    "description": "Open benchmarks for Agents — verified leaderboards for build vs buy decisions on AI agent tooling."
                  },
                  "last_updated": "2026-05-13T22:00:00.000Z",
                  "leaderboards": [
                    {
                      "slug": "work-email-enrichment",
                      "name": "Work Email Enrichment Benchmark",
                      "page_url": "https://benchmarks.openfunnel.dev/leaderboards/work-email-enrichment",
                      "api_url": "https://benchmarks.openfunnel.dev/api/leaderboards/work-email-enrichment",
                      "input_modes": [
                        "basic",
                        "rich"
                      ],
                      "provider_count": 3,
                      "winners": {
                        "most_correct": {
                          "provider": "FullEnrich",
                          "correct_email_rate_pct": 84.33
                        },
                        "least_wrong": {
                          "provider": "ContactOut",
                          "wrong_email_rate_pct": 5.53
                        },
                        "cheapest_per_correct": {
                          "provider": "Fiber",
                          "cost_per_correct_email_usd": 0.05
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Leaderboard data temporarily unavailable. Retry after the Retry-After header.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "data_unavailable",
                  "message": "Leaderboard data is temporarily unavailable. Retry shortly or check status at /api/leaderboards.",
                  "retry_after_seconds": 60
                }
              }
            }
          }
        }
      }
    },
    "/api/leaderboards/{slug}": {
      "get": {
        "tags": [
          "leaderboards"
        ],
        "summary": "Get a leaderboard by slug",
        "description": "Returns full per-provider results for a benchmark, including both the rich and basic input slices. Safe to call without authentication.",
        "operationId": "getLeaderboard",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "work-email-enrichment"
              ]
            },
            "description": "Leaderboard slug. Currently only 'work-email-enrichment' is published.",
            "example": "work-email-enrichment"
          }
        ],
        "responses": {
          "200": {
            "description": "Full leaderboard data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Leaderboard"
                },
                "example": {
                  "slug": "work-email-enrichment",
                  "name": "Work Email Enrichment Benchmark",
                  "last_updated": "2026-05-13T22:00:00.000Z",
                  "license": "https://creativecommons.org/licenses/by/4.0/",
                  "input_modes": {
                    "rich": {
                      "slug": "rich",
                      "description": "Provider receives first name, last name, company, and the contact's LinkedIn profile URL."
                    },
                    "basic": {
                      "slug": "basic",
                      "description": "Provider receives first name, last name, and company only."
                    }
                  },
                  "results": {
                    "rich": [
                      {
                        "rank": 1,
                        "provider": "FullEnrich",
                        "provider_slug": "fullenrich",
                        "homepage": "https://fullenrich.com",
                        "input_mode": "rich",
                        "correct_email_rate_pct": 84.33,
                        "wrong_email_rate_pct": 8.12,
                        "answer_rate_pct": 92.45,
                        "accuracy_when_answered_pct": 91.22,
                        "cost_per_correct_email_usd": 0.18,
                        "total_contacts": 480
                      }
                    ],
                    "basic": []
                  },
                  "methodology_url": "https://benchmarks.openfunnel.dev/leaderboards/work-email-enrichment#methodology"
                }
              }
            }
          },
          "404": {
            "description": "Leaderboard slug not recognized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "leaderboard_not_found",
                  "message": "No leaderboard with slug 'unknown'. See /api/leaderboards for the list.",
                  "available": [
                    "work-email-enrichment"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Leaderboard data temporarily unavailable. Retry after the Retry-After header.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LeaderboardIndex": {
        "type": "object",
        "properties": {
          "site": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "url"
            ]
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          },
          "leaderboards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeaderboardSummary"
            }
          },
          "docs": {
            "type": "object",
            "properties": {
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "llms": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "mcp": {
            "type": "object",
            "description": "Native Model Context Protocol endpoint exposing OpenFunnel data as tools, prompts, and resources. OAuth 2.1 with dynamic client registration.",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "transport": {
                "type": "string",
                "enum": [
                  "http"
                ]
              },
              "protocol_version": {
                "type": "string"
              },
              "capabilities": {
                "type": "object",
                "properties": {
                  "tools": {
                    "type": "boolean"
                  },
                  "prompts": {
                    "type": "boolean"
                  },
                  "resources": {
                    "type": "boolean"
                  },
                  "tasks": {
                    "type": "boolean"
                  }
                }
              },
              "auth": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "oauth2"
                    ]
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "dynamic_registration": {
                    "type": "boolean"
                  },
                  "metadata_url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              },
              "discovery": {
                "type": "string",
                "format": "uri"
              },
              "documentation": {
                "type": "string",
                "format": "uri"
              },
              "description": {
                "type": "string"
              }
            }
          }
        },
        "required": [
          "site",
          "last_updated",
          "leaderboards"
        ]
      },
      "LeaderboardSummary": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "page_url": {
            "type": "string",
            "format": "uri"
          },
          "api_url": {
            "type": "string",
            "format": "uri"
          },
          "metrics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metric"
            }
          },
          "input_modes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "basic",
                "rich"
              ]
            }
          },
          "provider_count": {
            "type": "integer",
            "minimum": 0
          },
          "winners": {
            "$ref": "#/components/schemas/Winners"
          }
        },
        "required": [
          "slug",
          "name",
          "page_url",
          "api_url"
        ]
      },
      "Leaderboard": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "page_url": {
            "type": "string",
            "format": "uri"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          },
          "license": {
            "type": "string",
            "format": "uri"
          },
          "metrics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metric"
            }
          },
          "input_modes": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "results": {
            "type": "object",
            "properties": {
              "rich": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProviderResult"
                }
              },
              "basic": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProviderResult"
                }
              }
            }
          },
          "methodology_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "slug",
          "name",
          "results"
        ]
      },
      "ProviderResult": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1
          },
          "provider": {
            "type": "string"
          },
          "provider_slug": {
            "type": "string"
          },
          "homepage": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "input_mode": {
            "type": "string",
            "enum": [
              "basic",
              "rich"
            ]
          },
          "correct_email_rate_pct": {
            "type": "number",
            "nullable": true
          },
          "wrong_email_rate_pct": {
            "type": "number",
            "nullable": true
          },
          "answer_rate_pct": {
            "type": "number",
            "nullable": true
          },
          "accuracy_when_answered_pct": {
            "type": "number",
            "nullable": true
          },
          "cost_per_correct_email_usd": {
            "type": "number",
            "nullable": true
          },
          "attempted_contacts": {
            "type": "integer",
            "nullable": true
          },
          "total_contacts": {
            "type": "integer"
          }
        },
        "required": [
          "rank",
          "provider",
          "provider_slug",
          "input_mode",
          "total_contacts"
        ]
      },
      "Metric": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "unit": {
            "type": "string",
            "enum": [
              "percent",
              "usd"
            ]
          },
          "direction": {
            "type": "string",
            "enum": [
              "higher_is_better",
              "lower_is_better"
            ]
          },
          "definition": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "label",
          "unit",
          "direction"
        ]
      },
      "Winners": {
        "type": "object",
        "properties": {
          "most_correct": {
            "type": "object",
            "nullable": true
          },
          "least_wrong": {
            "type": "object",
            "nullable": true
          },
          "cheapest_per_correct": {
            "type": "object",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "available": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "retry_after_seconds": {
            "type": "integer"
          }
        },
        "required": [
          "error",
          "message"
        ]
      }
    }
  }
}