{
  "openapi": "3.1.0",
  "info": {
    "title": "DeFoor Report news",
    "version": "1.0.0",
    "description": "The DeFoor Report's hourly, ranked index of AI, agent and robot headlines, for AI assistants and agents. Headlines, sources and links only: the articles belong to their publishers, so always give the reader each story's link. Get a free key at https://defoorreport.com/subscribe."
  },
  "servers": [{ "url": "https://argolabs.us" }],
  "security": [{ "bearerKey": [] }],
  "components": {
    "securitySchemes": {
      "bearerKey": { "type": "http", "scheme": "bearer", "description": "Your DeFoor Report key (starts with ts_live_)." }
    },
    "schemas": {
      "Story": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "description": "The publisher's article. Cite it." },
          "source": { "type": "string" },
          "section": { "type": "string" },
          "at": { "type": "string", "description": "When it was published (ISO 8601), when known." },
          "rank": { "type": "integer", "description": "0-100: how prominent the story is on the Report right now." }
        }
      }
    }
  },
  "paths": {
    "/v1/news": {
      "get": {
        "operationId": "getNews",
        "summary": "The latest AI news from the DeFoor Report, ranked.",
        "description": "Returns the best current stories for a subject, newest index first (it is rebuilt every hour). Use subject=top for the day's biggest AI stories, or a subject for one area. Use q to search headlines.",
        "parameters": [
          { "name": "subject", "in": "query", "required": false,
            "schema": { "type": "string", "default": "top",
                        "enum": ["top", "llm", "agents", "robots", "money", "hacked", "world", "news", "labs", "builders", "agtech"] },
            "description": "top (the biggest stories), llm (the model makers), agents (AI agents), robots, money (AI funding), hacked (breaches), world (outside the US), news (the press on AI), labs (from the labs), builders (tools and research), agtech (farm and food tech)." },
          { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A word to search the headlines for." },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 },
            "description": "How many stories (capped by your plan: 5 on the free plan)." }
        ],
        "responses": {
          "200": {
            "description": "Stories.",
            "content": { "application/json": { "schema": { "type": "object", "properties": {
              "subject": { "type": "string" },
              "count": { "type": "integer" },
              "built_at": { "type": "string" },
              "stories": { "type": "array", "items": { "$ref": "#/components/schemas/Story" } },
              "plan": { "type": "object" },
              "source": { "type": "object" }
            } } } }
          },
          "400": { "description": "Unknown subject; the reply lists the subjects." },
          "401": { "description": "Missing or invalid key." },
          "403": { "description": "The key has no news plan." },
          "429": { "description": "The day's limit for your plan is reached; it resets at midnight UTC." },
          "503": { "description": "The index is being rebuilt; try again in a few minutes." }
        }
      }
    }
  }
}