{
  "openapi": "3.1.0",
  "info": {
    "title": "Modelwire Developer API",
    "version": "1.0.0",
    "description": "Curated AI news as JSON: original headlines, summaries, editorial analysis, buzz scores, and links to original reporting. Free during beta (1,000 requests/day). Get a key at https://themodelwire.com/developers",
    "contact": { "email": "hello@themodelwire.com", "url": "https://themodelwire.com/developers" }
  },
  "servers": [{ "url": "https://api.themodelwire.com/v1/public" }],
  "security": [{ "ApiKeyHeader": [] }],
  "paths": {
    "/articles": {
      "get": {
        "summary": "List published articles, newest first",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category slug (see /categories)" },
          { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Source slug (see /sources)" },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Text search over headline, summary, entities" },
          { "name": "before", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor: unix ms or ISO 8601. Use nextCursor from the previous page." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Article page",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "articles": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } },
                    "nextCursor": { "type": ["string", "null"], "description": "Pass as `before` to fetch the next page" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/articles/top": {
      "get": {
        "summary": "Current top stories by buzz score",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 8, "default": 5 } }
        ],
        "responses": {
          "200": {
            "description": "Top articles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "articles": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/articles/{id}": {
      "get": {
        "summary": "One article plus related articles",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "26-char article ULID" }
        ],
        "responses": {
          "200": {
            "description": "Article detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "article": { "$ref": "#/components/schemas/Article" },
                    "related": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }
                  }
                }
              }
            }
          },
          "404": { "description": "Unknown or unpublished article" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/categories": {
      "get": {
        "summary": "Category catalog with article counts",
        "responses": {
          "200": {
            "description": "Categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string" },
                          "name": { "type": "string" },
                          "description": { "type": "string" },
                          "articleCount": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/sources": {
      "get": {
        "summary": "Source catalog",
        "responses": {
          "200": {
            "description": "Sources",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string" },
                          "name": { "type": "string" },
                          "homepage": { "type": "string" },
                          "kind": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/briefing": {
      "get": {
        "summary": "Today's Daily Landscape synthesis",
        "responses": {
          "200": {
            "description": "Briefing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "content": { "type": "string" }
                  }
                }
              }
            }
          },
          "404": { "description": "No briefing available yet" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Free key from https://themodelwire.com/developers"
      }
    },
    "responses": {
      "Unauthorized": { "description": "Missing, malformed, or revoked API key" },
      "RateLimited": {
        "description": "Daily quota exceeded. Check x-ratelimit-* headers; resets at midnight UTC."
      }
    },
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "26-char ULID" },
          "headline": { "type": "string", "description": "Modelwire's original headline" },
          "sourceHeadline": { "type": "string", "description": "The publisher's original headline (attribution)" },
          "sourceUrl": { "type": "string", "format": "uri", "description": "The original article. Link to this when displaying content." },
          "modelwireUrl": { "type": "string", "format": "uri" },
          "summary": { "type": "string", "description": "80-120 word original synthesis" },
          "whyItMatters": { "type": ["string", "null"] },
          "analysis": {
            "type": ["object", "null"],
            "properties": {
              "voice": { "type": "string", "enum": ["skeptical", "explainer", "analyst"] },
              "whatsNew": { "type": "string" },
              "howThisFits": { "type": "string" },
              "whatToWatch": { "type": "string" },
              "generatedAt": { "type": "string", "format": "date-time" }
            }
          },
          "source": {
            "type": "object",
            "properties": {
              "slug": { "type": "string" },
              "name": { "type": "string" }
            }
          },
          "categories": { "type": "array", "items": { "type": "string" } },
          "entities": { "type": "array", "items": { "type": "string" } },
          "buzzScore": { "type": "integer", "minimum": 0, "maximum": 100 },
          "publishedAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "imageUrl": { "type": ["string", "null"], "format": "uri" }
        }
      }
    }
  }
}