{
  "openapi": "3.0.3",
  "info": {
    "title": "FintechBulletins API",
    "version": "1.0.0",
    "description": "Public API for FintechBulletins — Pakistan fintech news, editorial, and newsletter delivery. This spec is referenced by the RFC 9727 API catalog at /.well-known/api-catalog.",
    "contact": {
      "name": "FintechBulletins",
      "url": "https://fintechbulletins.com/contact"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    { "url": "https://fintechbulletins.com", "description": "Production (public API gateway)" }
  ],
  "tags": [
    { "name": "articles", "description": "Live fintech news articles" },
    { "name": "editorial", "description": "Original long-form editorial content" },
    { "name": "newsletter", "description": "Daily digest subscription" },
    { "name": "ai", "description": "AI expansion and chat" },
    { "name": "system", "description": "Health and status" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["system"],
        "summary": "Service health and index stats",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "articles": { "type": "integer" },
                    "editorial": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/articles": {
      "get": {
        "tags": ["articles"],
        "summary": "Latest scraped articles (list, no full body)",
        "operationId": "listArticles",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "rerank", "in": "query", "schema": { "type": "boolean", "description": "LLM-rerank the feed" } }
        ],
        "responses": {
          "200": {
            "description": "Article list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "articles": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ArticleSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/articles/{article_id}": {
      "get": {
        "tags": ["articles"],
        "summary": "Single article with full body",
        "operationId": "getArticle",
        "parameters": [
          { "name": "article_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Article with full content",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Article" }
              }
            }
          }
        }
      }
    },
    "/api/expand": {
      "post": {
        "tags": ["ai"],
        "summary": "Expand a short article into a full briefing with AI",
        "operationId": "expandArticle",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "title": { "type": "string" },
                  "content": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Expanded article text" } }
      }
    },
    "/api/chat": {
      "post": {
        "tags": ["ai"],
        "summary": "Chat with the FintechBulletins assistant",
        "operationId": "chat",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": { "type": "string" },
                  "history": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Assistant reply" } }
      }
    },
    "/api/subscribe": {
      "post": {
        "tags": ["newsletter"],
        "summary": "Subscribe an email to the daily digest",
        "operationId": "subscribe",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscribed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "email": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/unsubscribe": {
      "get": {
        "tags": ["newsletter"],
        "summary": "Unsubscribe an email from the daily digest",
        "operationId": "unsubscribe",
        "parameters": [
          { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email" } }
        ],
        "responses": { "200": { "description": "Unsubscribed" } }
      }
    },
    "/api/editorial": {
      "get": {
        "tags": ["editorial"],
        "summary": "List published editorial articles",
        "operationId": "listEditorial",
        "responses": {
          "200": {
            "description": "Editorial list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "articles": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/EditorialSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/editorial/{slug}": {
      "get": {
        "tags": ["editorial"],
        "summary": "Single editorial article",
        "operationId": "getEditorial",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Editorial article",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Editorial" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArticleSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "category": { "type": "string" },
          "source": { "type": "string" },
          "published": { "type": "string", "format": "date-time" },
          "image": { "type": "string", "nullable": true },
          "summary": { "type": "string" }
        }
      },
      "Article": {
        "allOf": [
          { "$ref": "#/components/schemas/ArticleSummary" },
          {
            "type": "object",
            "properties": {
              "content": { "type": "string" },
              "link": { "type": "string", "nullable": true }
            }
          }
        ]
      },
      "EditorialSummary": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "category": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Editorial": {
        "allOf": [
          { "$ref": "#/components/schemas/EditorialSummary" },
          {
            "type": "object",
            "properties": {
              "content": { "type": "string" },
              "created_by": { "type": "string" }
            }
          }
        ]
      }
    }
  }
}