{
  "openapi": "3.1.0",
  "info": {
    "title": "AIMode News API",
    "version": "1.0.0",
    "description": "Public read-only API for the AIMode News aggregation platform. Returns latest AI, technology, science, and business headlines with summaries. No authentication required; responses are cache-friendly and suitable for AI agents, RAG pipelines, and research use.",
    "contact": {
      "name": "AIMode News",
      "url": "https://www.aimode.news"
    }
  },
  "servers": [
    {
      "url": "https://www.aimode.news"
    }
  ],
  "paths": {
    "/api/news": {
      "get": {
        "operationId": "getLatestNews",
        "summary": "Get the latest news articles",
        "description": "Returns the most recent articles with title, summary, category, source, and canonical URL. Filter by entity slug (e.g. openai, google, nvidia) or category (AI, Technology, World, Science, Business, Health).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Number of articles to return (1-100)."
          },
          {
            "name": "entity",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Entity slug filter, e.g. openai, xai, spacex."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "AI",
                "Technology",
                "World",
                "Science",
                "Business",
                "Health"
              ]
            },
            "description": "Category filter."
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30,
              "minimum": 1,
              "maximum": 365
            },
            "description": "Only return articles published within this many days."
          }
        ],
        "responses": {
          "200": {
            "description": "Article list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "articles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Article"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown category or invalid parameters"
          },
          "503": {
            "description": "Feed temporarily unavailable"
          }
        }
      }
    },
    "/api/topics": {
      "get": {
        "operationId": "getTopics",
        "summary": "Get the list of company/entity topic hubs",
        "description": "Returns enabled entity hubs (OpenAI, Google, Apple, Nvidia, etc.) with hand-written descriptions and links to their topic pages.",
        "responses": {
          "200": {
            "description": "Topic list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "topics": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "getSearchResults",
        "summary": "Search headlines and summaries by keyword",
        "description": "Full-text search across AIMode News articles. Returns matching articles ranked by relevance.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 100
            },
            "description": "Search query (2+ characters)."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            },
            "description": "Number of results to return."
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "articles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Article"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or too-short q parameter"
          },
          "503": {
            "description": "Feed temporarily unavailable"
          }
        }
      }
    },
    "/api/trending": {
      "get": {
        "operationId": "getTrending",
        "summary": "Get the most-viewed articles right now",
        "description": "Returns the currently most-viewed articles, useful for what-is-trending queries.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            },
            "description": "Number of results to return."
          }
        ],
        "responses": {
          "200": {
            "description": "Trending articles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "articles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Article"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Feed temporarily unavailable"
          }
        }
      }
    },
    "/api/categories": {
      "get": {
        "operationId": "getCategories",
        "summary": "Get the list of editorial categories",
        "description": "Returns the site's categories with descriptions and current article counts.",
        "responses": {
          "200": {
            "description": "Category list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "articleCount": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Feed temporarily unavailable"
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "operationId": "getAgentRegistry",
        "summary": "Get machine-verified AI agents registered with AIMode News",
        "description": "Returns AI agents that self-registered and passed A2A agent-card verification. Agents register via POST /api/agents/register.",
        "responses": {
          "200": {
            "description": "Agent list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "agents": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "cardUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "homepageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "skills": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "verifiedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/article/{slug}": {
      "get": {
        "operationId": "getArticleBySlug",
        "summary": "Get a single article by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Article slug, e.g. upcoming-and-recent-ipos-ipos-calendar-1994e858."
          }
        ],
        "responses": {
          "200": {
            "description": "Article detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "article": {
                      "$ref": "#/components/schemas/Article"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Article not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Original publisher URL"
          },
          "canonical": {
            "type": "string",
            "format": "uri",
            "description": "AIMode News canonical URL"
          },
          "sourceName": {
            "type": "string"
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": "string"
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "lang": {
            "type": "string"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      }
    }
  }
}