{
  "openapi": "3.1.0",
  "info": {
    "title": "BIP Explorer API",
    "version": "1.0.0",
    "description": "Read-only access to every Bitcoin Improvement Proposal (BIP): metadata, plain-English summaries, full rendered text, topics and revision history, generated from github.com/bitcoin/bips. No authentication. Statuses follow BIP 3: Draft, Complete, Deployed, Closed. An MCP server with the same data is available at https://bipexplorer.com/mcp.",
    "contact": { "url": "https://x.com/BIPExplorer" }
  },
  "servers": [{ "url": "https://bipexplorer.com" }],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchBips",
        "summary": "Search BIPs by keyword or number",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Keywords (e.g. 'taproot', 'seed phrase', an author) or a BIP number ('341')." },
          { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/Status" } },
          { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/Type" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }
        ],
        "responses": {
          "200": {
            "description": "Matches, best first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": { "type": "string" },
                    "count": { "type": "integer" },
                    "results": { "type": "array", "items": { "$ref": "#/components/schemas/BipCard" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bips": {
      "get": {
        "operationId": "listBips",
        "summary": "All BIPs (metadata, summary and abstract; no full text)",
        "responses": { "200": { "description": "Every BIP", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BipSummary" } } } } } }
      }
    },
    "/api/bips/{number}": {
      "get": {
        "operationId": "getBip",
        "summary": "One BIP including its rendered HTML, table of contents and revision history",
        "parameters": [{ "name": "number", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "The BIP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bip" } } } },
          "404": { "description": "No BIP with that number" }
        }
      }
    },
    "/bip/{number}.md": {
      "get": {
        "operationId": "getBipMarkdown",
        "summary": "One BIP as Markdown with a YAML metadata header (best for language models)",
        "parameters": [{ "name": "number", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Markdown document", "content": { "text/markdown": { "schema": { "type": "string" } } } } }
      }
    },
    "/api/bips/{number}/timeline": {
      "get": {
        "operationId": "getBipHistory",
        "summary": "Revision history of a BIP in bitcoin/bips (newest first)",
        "parameters": [{ "name": "number", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "History", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/History" } } } } }
      }
    },
    "/api/topics": {
      "get": {
        "operationId": "listTopics",
        "summary": "Topics with descriptions and BIP counts",
        "responses": { "200": { "description": "Topics", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Topic" } } } } } }
      }
    },
    "/api/authors/{name}/bips": {
      "get": {
        "operationId": "getBipsByAuthor",
        "summary": "BIPs by one author (exact name, case-insensitive)",
        "parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "BIPs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BipSummary" } } } } } }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Counts by status and type",
        "responses": { "200": { "description": "Statistics", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "integer" } } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Status": { "type": "string", "enum": ["Draft", "Complete", "Deployed", "Closed"], "description": "Draft: being written. Complete: finished, awaiting adoption. Deployed: live. Closed: withdrawn, rejected or replaced." },
      "Type": { "type": "string", "enum": ["Specification", "Informational", "Process"] },
      "BipCard": {
        "type": "object",
        "properties": {
          "number": { "type": "integer" },
          "title": { "type": "string" },
          "status": { "$ref": "#/components/schemas/Status" },
          "impact": { "type": ["integer", "null"], "minimum": 0, "maximum": 100, "description": "Percentile rank of this BIP's influence: how often other BIPs reference it, then how much it has been revised." },
          "core": { "type": "boolean", "description": "One of the 20 live BIPs with the highest impact." },
          "type": { "$ref": "#/components/schemas/Type" },
          "layer": { "type": ["string", "null"] },
          "authors": { "type": "array", "items": { "type": "string" } },
          "assigned": { "type": ["string", "null"], "format": "date" },
          "lastModified": { "type": ["string", "null"], "format": "date" },
          "topics": { "type": "array", "items": { "type": "string" } },
          "summary": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "markdown": { "type": "string", "format": "uri" },
          "source": { "type": "string", "format": "uri" },
          "score": { "type": "number" }
        }
      },
      "BipSummary": {
        "type": "object",
        "properties": {
          "number": { "type": "integer" },
          "title": { "type": "string" },
          "authors": { "type": "array", "items": { "type": "string" } },
          "status": { "$ref": "#/components/schemas/Status" },
          "impact": { "type": "integer", "minimum": 0, "maximum": 100 },
          "core": { "type": "boolean" },
          "inbound": { "type": "integer", "description": "How many other BIPs link to this one." },
          "revisions": { "type": "integer", "description": "Number of commits that changed this BIP." },
          "type": { "$ref": "#/components/schemas/Type" },
          "layer": { "type": "string" },
          "created": { "type": "string", "description": "Date the number was assigned (YYYY-MM-DD)." },
          "lastModified": { "type": "string", "description": "Date of the last change (YYYY-MM-DD)." },
          "license": { "type": "string" },
          "requires": { "type": "array", "items": { "type": "integer" } },
          "replaces": { "type": "array", "items": { "type": "integer" } },
          "replacedBy": { "type": "array", "items": { "type": "integer" } },
          "discussion": { "type": "array", "items": { "type": "string", "format": "uri" } },
          "abstract": { "type": "string" },
          "eli5": { "type": "string", "description": "Plain-English summary." },
          "categories": { "type": "array", "items": { "type": "string" }, "description": "Topic ids." },
          "filename": { "type": "string" },
          "githubUrl": { "type": "string", "format": "uri" },
          "readingMinutes": { "type": "integer" }
        }
      },
      "Bip": {
        "allOf": [
          { "$ref": "#/components/schemas/BipSummary" },
          {
            "type": "object",
            "properties": {
              "html": { "type": "string", "description": "Rendered, sanitized specification." },
              "toc": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "level": { "type": "integer" } } } },
              "history": { "$ref": "#/components/schemas/History" }
            }
          }
        ]
      },
      "History": {
        "type": "object",
        "properties": {
          "totalCommits": { "type": "integer" },
          "firstCommit": { "type": ["string", "null"], "format": "date-time" },
          "lastUpdated": { "type": ["string", "null"], "format": "date-time" },
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "sha": { "type": "string" },
                "date": { "type": "string", "format": "date-time" },
                "author": { "type": "string" },
                "message": { "type": "string" },
                "url": { "type": "string", "format": "uri" },
                "kind": { "type": "string", "enum": ["status", "rename", "edit"] }
              }
            }
          }
        }
      },
      "Topic": {
        "type": "object",
        "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "group": { "type": "string" }, "count": { "type": "integer" } }
      }
    }
  }
}