{
  "openapi": "3.1.0",
  "info": {
    "title": "gitBeacon API",
    "version": "1.0.0",
    "x-guidance": "gitBeacon — pay-per-call GitHub trend intelligence for AI agents on x402 (USDC on Base Mainnet, eip155:8453). FREE (no key, no payment, rate-limited): GET /v1/index (poll for new digests, 24h cadence), /v1/brief (field-trimmed current digest), /v1/sample (frozen 2026-02-13 digest to learn the shape), /v1/digests/latest (most recent full digest). PAID (x402): GET /v1/repos ($0.01 — top trending repos from the latest daily scan, filterable by language) and GET /v1/digests ($0.05 — historical daily digests, 1-30 day lookback). Pay flow: call a paid route with no payment -> receive HTTP 402 (the x402 V2 PaymentRequirements ride in the base64 PAYMENT-REQUIRED header; the JSON body mirrors price+accepts) -> sign an EIP-3009 `exact` USDC authorization on Base for the accepts[] amount -> retry the same request with the payment in the PAYMENT-SIGNATURE (V2) or X-PAYMENT (legacy) header. Stock x402 clients (@x402/fetch, @x402/axios, python x402) do this automatically. No accounts or API keys required. Compute-first / settle-after: you are never charged for an error.",
    "summary": "GitHub trend intelligence for AI agents on x402 — daily LLM-analyzed digests of trending new repos plus the raw trending-repo data. Per-call, no signup.",
    "description": "gitBeacon — GitHub trend intelligence for AI agents. A daily scan of trending new GitHub repos, LLM-analyzed into a structured digest (title, summary, top categories, language trends, emerging tools, notable projects, and overall sentiment), plus the raw trending-repo rows behind it (stars, forks, language, topics, license, author, README excerpt). Poll for free to detect new digests (/v1/index), read the field-trimmed brief and the latest full digest for free, or grab a frozen sample to learn the response shape. Paid endpoints settle per call via x402 micropayments (USDC on Base Mainnet) — no account, no API key.",
    "termsOfService": "https://api.gitbeacon.dev/terms.txt",
    "contact": {
      "name": "gitBeacon API",
      "url": "https://api.gitbeacon.dev"
    }
  },
  "servers": [
    {
      "url": "https://api.gitbeacon.dev",
      "description": "gitBeacon API public edge"
    }
  ],
  "externalDocs": {
    "description": "Agent-facing reference (llms.txt)",
    "url": "https://api.gitbeacon.dev/llms.txt"
  },
  "tags": [
    {
      "name": "free",
      "description": "No auth, no payment."
    },
    {
      "name": "paid",
      "description": "x402 V2 per-call pricing (USDC on eip155:8453)."
    }
  ],
  "paths": {
    "/v1/brief": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "brief",
        "summary": "GitHub digest brief",
        "description": "Free (rate-limited 10/min per IP). Field-trimmed snapshot of the current daily GitHub digest — title, summary, top categories, language trends, overall sentiment, and digestDate. Full digest at GET /v1/digests/latest (free).",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "data": {
                      "title": "AI-Powered Development Takes Center Stage",
                      "summary": "Today's GitHub activity showcases a surge in AI-driven projects...",
                      "topCategories": [
                        "AI/ML: AI-powered development tools",
                        "DevTools: IDEs and editors",
                        "Security"
                      ],
                      "languageTrends": [
                        "Python: dominant in AI/ML",
                        "Rust: growing in systems",
                        "TypeScript: gaining traction"
                      ],
                      "overallSentiment": "innovative",
                      "digestDate": "2026-02-13T00:00:00.000Z",
                      "createdAt": "2026-02-14T18:12:04.340Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/index": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "index",
        "summary": "GitHub digest index",
        "description": "Free (rate-limited 10/min per IP). Poll target — returns the current digest id, digestDate, and updatedAt plus the nextExpected time (24h cadence), so agents detect new digests without paying.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "index": "clx0digest123",
                    "digestDate": "2026-02-13T00:00:00.000Z",
                    "updatedAt": "2026-02-14T18:12:04.340Z",
                    "cadence": "every 24 hours",
                    "nextExpected": "2026-02-15T18:12:04.340Z"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/sample": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "sample",
        "summary": "Sample GitHub digest",
        "description": "Free (rate-limited 5/min per IP). A FROZEN sample digest captured from the 2026-02-13 scan — the same shape as a real digest, but it never changes. Use it to learn the response contract before paying.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "data": {
                      "id": "sample-github-digest",
                      "digestDate": "2026-02-13T00:00:00.000Z",
                      "title": "AI-Powered Development Takes Center Stage",
                      "overallSentiment": "innovative",
                      "totalReposAnalyzed": 50
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/digests/latest": {
      "get": {
        "tags": [
          "free"
        ],
        "operationId": "digests-latest",
        "summary": "Latest GitHub digest",
        "description": "Free (rate-limited 5/min per IP). The most recent completed daily GitHub digest with full fields: fullAnalysis, notableProjects, emergingTools, language trends, and volume metrics.",
        "security": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "data": {
                      "id": "clx0digest123",
                      "digestDate": "2026-02-13T00:00:00.000Z",
                      "title": "AI-Powered Development Takes Center Stage",
                      "summary": "AI-driven projects dominate...",
                      "topCategories": [
                        "AI/ML",
                        "DevTools",
                        "Security"
                      ],
                      "notableProjects": [
                        {
                          "name": "HKUDS/FastCode",
                          "stars": 321,
                          "language": "Python"
                        }
                      ],
                      "totalReposAnalyzed": 50,
                      "overallSentiment": "innovative"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/repos": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "repos",
        "summary": "Top trending repos ($0.01)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "Paid ($0.01 USDC via x402). Top trending GitHub repos from the latest daily scan, sorted by stars — description, language, topics, license, forks, author followers, and README excerpt. Filterable by programming language. Response carries the scanDate provenance. Compute-first / settle-after — you are never charged for an error.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 30
            },
            "description": "Max repos to return (1-100)."
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by programming language, case-insensitive (e.g. Python, Rust, TypeScript)."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "scanDate": "2026-02-25T00:00:00.000Z",
                    "count": 30,
                    "data": [
                      {
                        "fullName": "HKUDS/FastCode",
                        "description": "Accelerates and streamlines code understanding",
                        "language": "Python",
                        "stars": 321,
                        "forks": 45,
                        "topics": [
                          "ai",
                          "code-understanding",
                          "llm"
                        ],
                        "license": "MIT",
                        "authorFollowers": 1200,
                        "readmeExcerpt": "FastCode is an AI-powered tool for accelerating code comprehension..."
                      }
                    ],
                    "charged": true
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    },
    "/v1/digests": {
      "get": {
        "tags": [
          "paid"
        ],
        "operationId": "digests",
        "summary": "Historical GitHub digests ($0.05)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.050000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "description": "Paid ($0.05 USDC via x402). Historical daily GitHub digests (1-30 day lookback). Track how open-source trends, language popularity, and emerging tools evolve over time — each digest carries the same rich analysis as /v1/digests/latest, keyed by digestDate provenance. Compute-first / settle-after — you are never charged for an error.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 7
            },
            "description": "Lookback window in days (1-30)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 30,
              "default": 7
            },
            "description": "Max digests to return (1-30)."
          }
        ],
        "security": [
          {
            "x402": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "success": true,
                    "count": 3,
                    "days": 7,
                    "limit": 7,
                    "data": [
                      {
                        "digestDate": "2026-02-25T00:00:00.000Z",
                        "title": "AI-Powered Development Takes Center Stage",
                        "summary": "AI-driven projects dominate...",
                        "topCategories": [
                          "AI/ML",
                          "DevTools",
                          "Security"
                        ],
                        "totalReposAnalyzed": 50,
                        "overallSentiment": "innovative"
                      }
                    ],
                    "charged": true
                  }
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "PaymentRequired": {
        "description": "x402 V2 payment challenge. Sign an `exact` USDC authorization for one accepts[] rail, then retry with the PAYMENT-SIGNATURE (V2) or X-PAYMENT (legacy) header. You are not charged for errors or below-threshold answers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PaymentRequired"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "x402": {
        "type": "http",
        "scheme": "x402",
        "description": "Custom HTTP 402 payment flow (x402 V2). The server answers an unpaid paid-route request with a 402 whose body is a PaymentRequired envelope (x402Version + accepts[] + terms). Each accepts[] entry is an `exact`-scheme USDC rail. Sign ONE rail and retry the same request with the `PAYMENT-SIGNATURE` header (x402 V2 clients) or the legacy `X-PAYMENT` header. Per-call pricing."
      }
    },
    "schemas": {
      "PaymentRequired": {
        "type": "object",
        "description": "x402 V2 PaymentRequired envelope. accepts[] lists one exact USDC rail per network.",
        "properties": {
          "x402Version": {
            "type": "integer",
            "const": 2
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": {
                  "type": "string",
                  "const": "exact"
                },
                "network": {
                  "type": "string",
                  "enum": [
                    "eip155:8453"
                  ]
                },
                "asset": {
                  "type": "string",
                  "const": "USDC"
                },
                "price": {
                  "type": "string",
                  "description": "USD price string."
                },
                "payTo": {
                  "type": "string",
                  "description": "Settlement address for this rail."
                },
                "mimeType": {
                  "type": "string",
                  "const": "application/json"
                }
              }
            }
          },
          "terms": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}