# gitBeacon API — Full Agent Reference (v1.0.0)

> Extended reference: every endpoint with full description, parameters, and an example JSON
> body. Compact version: https://api.gitbeacon.dev/llms.txt · OpenAPI: https://api.gitbeacon.dev/openapi.json

## Base URL & discovery surface
- API base: https://api.gitbeacon.dev
- /llms.txt (compact) · /llms-full.txt (this) · /discovery (JSON enumeration)
- /openapi.json (OpenAPI 3.1) · /.well-known/x402 · /.well-known/agent-card.json
- Payment: x402 V2 · Networks: eip155:8453 · Asset: USDC · Scheme: exact

## GET /v1/brief   (FREE)
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).

Rate limit: 10/min.

Example response:
```json
{
  "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"
  }
}
```

## GET /v1/index   (FREE)
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.

Rate limit: 10/min.

Example response:
```json
{
  "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"
}
```

## GET /v1/sample   (FREE)
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.

Rate limit: 5/min.

Example response:
```json
{
  "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
  }
}
```

## GET /v1/digests/latest   (FREE)
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.

Rate limit: 5/min.

Example response:
```json
{
  "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"
  }
}
```

## GET /v1/repos   ($0.01)
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:
- `limit` (integer, query, optional) — Max repos to return (1-100).
- `language` (string, query, optional) — Filter by programming language, case-insensitive (e.g. Python, Rust, TypeScript).

Settlement: compute-first.

Example response:
```json
{
  "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
}
```

## GET /v1/digests   ($0.05)
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:
- `days` (integer, query, optional) — Lookback window in days (1-30).
- `limit` (integer, query, optional) — Max digests to return (1-30).

Settlement: compute-first.

Example response:
```json
{
  "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
}
```

## Payment
Strictly pay-per-call. An unpaid paid-route request returns a 402 challenge whose accepts[] lists one exact USDC rail per network (Base). Sign one rail and retry with PAYMENT-SIGNATURE (x402 V2) or X-PAYMENT (legacy).