{
  "openapi": "3.1.0",
  "info": {
    "title": "Agentic News API",
    "version": "0.1.0",
    "description": "Agent-facing API. Metadata and every discovery document are free. Full article bodies are sold over HTTP 402 with x402; the paying wallet address is the identity, and reading and training are separate grants.",
    "license": {
      "name": "See RSL terms",
      "url": "https://agenticnews.io/rsl.xml"
    }
  },
  "servers": [
    {
      "url": "https://agenticnews.io"
    }
  ],
  "paths": {
    "/catalog.json": {
      "get": {
        "summary": "The complete free catalogue",
        "description": "Every article with topics, representative queries, digests, prices and the grant each price carries. Static asset; no key, no rate limit.",
        "responses": {
          "200": {
            "description": "The catalogue"
          }
        }
      }
    },
    "/articles/{slug}.md": {
      "get": {
        "summary": "An article as Markdown",
        "description": "Free articles return the full body. Paid articles return metadata, the abstract and a purchase pointer.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown"
          },
          "404": {
            "description": "Unknown slug"
          }
        }
      }
    },
    "/a/{slug}": {
      "get": {
        "summary": "Read an article, paying if required",
        "description": "Content-negotiated. Free articles are returned directly. Paid articles return 402 with the offers below.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "html",
                "md",
                "json",
                "jsonld"
              ]
            }
          }
        ],
        "x-payment-info": {
          "offers": [
            {
              "intent": "charge",
              "method": "x402",
              "amount": "0.02",
              "currency": "USD",
              "description": "Single article, full text. Permits ai-input; does not permit ai-train.",
              "grants": {
                "read": true,
                "aiInput": true,
                "aiTrain": false
              },
              "licence": "https://agenticnews.io/licence/paid-read-v1"
            }
          ]
        },
        "responses": {
          "200": {
            "description": "The article"
          },
          "402": {
            "description": "Payment required; the body lists every offer"
          },
          "404": {
            "description": "Unknown slug"
          },
          "406": {
            "description": "No acceptable representation"
          }
        }
      }
    },
    "/api/passes/30d": {
      "post": {
        "summary": "Buy a 30-day reader pass",
        "description": "One settlement, one wallet-keyed entitlement, thirty days. No recurring mandate and no account.",
        "x-payment-info": {
          "offers": [
            {
              "intent": "charge",
              "method": "x402",
              "amount": "1.50",
              "currency": "USD",
              "description": "30-day reader pass. Permits ai-input; does not permit ai-train.",
              "grants": {
                "read": true,
                "aiInput": true,
                "aiTrain": false
              },
              "licence": "https://agenticnews.io/licence/paid-read-v1"
            }
          ]
        },
        "responses": {
          "201": {
            "description": "Pass issued"
          },
          "402": {
            "description": "Payment required"
          },
          "501": {
            "description": "Settlement lands in Phase 7"
          }
        }
      }
    },
    "/api/bundles/{month}": {
      "post": {
        "summary": "Buy a calendar month archive, with the AI-training grant",
        "description": "The only SKU that grants ai-train, over the corpus published in that month.",
        "parameters": [
          {
            "name": "month",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$"
            }
          }
        ],
        "x-payment-info": {
          "offers": [
            {
              "intent": "charge",
              "method": "x402",
              "amount": "5.00",
              "currency": "USD",
              "description": "One month of articles, including the ai-train grant.",
              "grants": {
                "read": true,
                "aiInput": true,
                "aiTrain": true
              },
              "licence": "https://agenticnews.io/licence/paid-train-v1"
            }
          ]
        },
        "responses": {
          "201": {
            "description": "Archive entitlement issued"
          },
          "402": {
            "description": "Payment required"
          },
          "501": {
            "description": "Settlement lands in Phase 7"
          }
        }
      }
    },
    "/api/articles/{slug}": {
      "get": {
        "summary": "Article metadata",
        "description": "Free. `?body=full` takes the entitlement path.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "body",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "full"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata"
          },
          "402": {
            "description": "Payment required for the body"
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Ranked search over the free catalogue",
        "description": "Free, no key. Returns titles, abstract snippets, topics, prices and the grants each price carries, plus a `coverage` object stating how much of the archive was searched — the index is capped, deliberately, so that the cost of a search cannot grow with the corpus.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            }
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked matches, with coverage"
          },
          "400": {
            "description": "Missing or too-short query"
          }
        }
      }
    },
    "/search-index.json": {
      "get": {
        "summary": "The bounded search index",
        "description": "Static asset. The most recent 500 articles with titles, abstract snippets, topics, representative queries, prices and digests. Use /catalog.json for complete coverage.",
        "responses": {
          "200": {
            "description": "The index"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP endpoint (streamable HTTP)",
        "description": "Model Context Protocol, revision 2026-07-28: stateless, POST only, no session and no initialize handshake. Methods: server/discover, tools/list, tools/call. Tools: search_articles, get_article, purchase_article. Payment over MCP is signalled inside the tool result — `isError: true` with the x402 `PaymentRequired` in `structuredContent` — and never as a 401; this server has no authorization scheme to fail. The connection document is the server card at /mcp/server-card.",
        "responses": {
          "200": {
            "description": "JSON-RPC result or error"
          },
          "202": {
            "description": "Notification accepted"
          },
          "400": {
            "description": "Header/body mismatch (-32020), missing per-request metadata (-32602) or unsupported protocol version (-32022)"
          },
          "403": {
            "description": "Invalid Origin header"
          },
          "404": {
            "description": "Unknown JSON-RPC method (-32601)"
          },
          "405": {
            "description": "GET or DELETE; this revision has no GET stream and no session"
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "summary": "Service status",
        "responses": {
          "200": {
            "description": "Status"
          }
        }
      }
    }
  }
}