{
  "openapi": "3.1.0",
  "info": {
    "title": "NestDaddy API",
    "version": "1.1.0",
    "summary": "Web search, news from 45+ countries, full page text and research papers as JSON.",
    "description": "NestDaddy is an independent search engine with its own web index. The API returns web results, news by key words, topic and country, the readable text of any public page, research papers, and data on AI tools, software and games. One All-in-One key covers every endpoint and the remote MCP server at https://mcp.nestdaddy.com/mcp. Get a key at https://nestdaddy.com/mcp.",
    "termsOfService": "https://nestdaddy.com/terms",
    "contact": { "name": "NestDaddy", "url": "https://nestdaddy.com", "email": "hello@nestdaddy.com" },
    "x-logo": { "url": "https://nestdaddy.com/static/android-chrome-512x512.png" }
  },
  "externalDocs": { "description": "API docs", "url": "https://nestdaddy.com/apis" },
  "servers": [{ "url": "https://nestdaddy.com" }],
  "security": [{ "ApiKeyHeader": [] }, { "ApiKeyQuery": [] }],
  "tags": [
    { "name": "Search", "description": "Web search on NestDaddy's own index" },
    { "name": "News", "description": "News search and latest headlines from 45+ countries" },
    { "name": "Pages", "description": "Readable text of public web pages" },
    { "name": "Research", "description": "Research papers" },
    { "name": "Directories", "description": "AI tools, software and games" }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "webSearch",
        "summary": "Web search",
        "description": "Pages from NestDaddy's own web index, cleaned of duplicates, with fresh news on top for time-sensitive questions.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string", "minLength": 1 } },
          { "$ref": "#/components/parameters/limit" },
          { "name": "sort", "in": "query", "description": "Result order", "schema": { "type": "string", "enum": ["relevance", "date"], "default": "relevance" } },
          { "name": "lang", "in": "query", "description": "Language filter, for example en or ms", "schema": { "type": "string" } },
          { "name": "news", "in": "query", "description": "Mix fresh news into time-sensitive results (1) or not (0)", "schema": { "type": "string", "enum": ["0", "1"], "default": "1" } },
          { "name": "external", "in": "query", "description": "Add answer cards from official open sources (1) or not (0)", "schema": { "type": "string", "enum": ["0", "1"], "default": "1" } }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/news/search": {
      "get": {
        "tags": ["News"],
        "operationId": "newsSearch",
        "summary": "Search news",
        "description": "Every article NestDaddy has collected from 45+ countries in the last 120 days, searched by key words.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "description": "Key words (2+ characters)", "schema": { "type": "string", "minLength": 2, "maxLength": 200 } },
          { "name": "country", "in": "query", "description": "Two-letter country code, for example MY, SG, ID, US, GB", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } },
          { "name": "topic", "in": "query", "schema": { "type": "string", "enum": ["global", "tech", "financial", "local"] } },
          { "name": "days", "in": "query", "description": "How many days back to search", "schema": { "type": "integer", "minimum": 1, "maximum": 120, "default": 30 } },
          { "$ref": "#/components/parameters/limit" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Matching articles",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/news/global": {
      "get": {
        "tags": ["News"],
        "operationId": "globalNews",
        "summary": "Latest world headlines",
        "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/newsCategory" }],
        "responses": {
          "200": { "description": "Latest articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlinesResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/news/tech": {
      "get": {
        "tags": ["News"],
        "operationId": "techNews",
        "summary": "Latest tech headlines",
        "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/newsCategory" }],
        "responses": {
          "200": { "description": "Latest articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlinesResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/news/financial": {
      "get": {
        "tags": ["News"],
        "operationId": "financialNews",
        "summary": "Latest markets, crypto and economy headlines",
        "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/newsCategory" }],
        "responses": {
          "200": { "description": "Latest articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlinesResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/news/local": {
      "get": {
        "tags": ["News"],
        "operationId": "countryNews",
        "summary": "Latest headlines from one country",
        "parameters": [
          { "name": "country", "in": "query", "description": "Two-letter country code", "schema": { "type": "string", "default": "MY" } },
          { "$ref": "#/components/parameters/limit" },
          { "name": "category", "in": "query", "schema": { "type": "string", "enum": ["all", "breaking", "business", "sports", "entertainment", "politics", "health", "science"], "default": "all" } }
        ],
        "responses": {
          "200": { "description": "Latest articles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadlinesResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/extract": {
      "get": {
        "tags": ["Pages"],
        "operationId": "readPage",
        "summary": "Readable text of a web page",
        "description": "Title, author, date and the main text of one public page, without menus or ads. Useful for RAG and for agents that need an article in full.",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } },
          { "name": "max_chars", "in": "query", "schema": { "type": "integer", "minimum": 500, "maximum": 30000, "default": 12000 } }
        ],
        "responses": {
          "200": { "description": "Page text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/research": {
      "get": {
        "tags": ["Research"],
        "operationId": "researchPapers",
        "summary": "Research papers",
        "description": "Papers from arXiv, PubMed, CORE, OpenAlex, CrossRef, Europe PMC and bioRxiv.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "default": "relevance" } },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/perPage" }
        ],
        "responses": {
          "200": { "description": "Papers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/aitools": {
      "get": {
        "tags": ["Directories"],
        "operationId": "aiTools",
        "summary": "AI models, tools and projects",
        "description": "New models with prices, trending models and apps, and fast-growing AI and MCP projects, updated daily.",
        "parameters": [
          { "$ref": "#/components/parameters/q" },
          { "name": "category", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "pricing", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "default": "popularity" } },
          { "$ref": "#/components/parameters/order" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/perPage" }
        ],
        "responses": {
          "200": { "description": "Items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/software": {
      "get": {
        "tags": ["Directories"],
        "operationId": "software",
        "summary": "Software and developer tools",
        "description": "Popular apps and developer tools with their current version and install command, updated daily.",
        "parameters": [
          { "$ref": "#/components/parameters/q" },
          { "name": "category", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "platform", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "pricing", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "default": "rating" } },
          { "$ref": "#/components/parameters/order" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/perPage" }
        ],
        "responses": {
          "200": { "description": "Items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/api/v1/games": {
      "get": {
        "tags": ["Directories"],
        "operationId": "games",
        "summary": "Games",
        "description": "Game data by genre and platform, sorted by rating, latest or trending.",
        "parameters": [
          { "$ref": "#/components/parameters/q" },
          { "name": "genre", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "platform", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "pricing", "in": "query", "schema": { "type": "string", "default": "all" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "default": "rating" } },
          { "$ref": "#/components/parameters/order" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/perPage" }
        ],
        "responses": {
          "200": { "description": "Items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" },
      "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "key" }
    },
    "parameters": {
      "limit": { "name": "limit", "in": "query", "description": "Number of results", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } },
      "newsCategory": { "name": "category", "in": "query", "description": "Sub-category filter", "schema": { "type": "string", "default": "all" } },
      "q": { "name": "q", "in": "query", "description": "Optional search words", "schema": { "type": "string" } },
      "order": { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } },
      "page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
      "perPage": { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }
    },
    "responses": {
      "BadRequest": { "description": "Missing or invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing, unknown or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "TooManyRequests": { "description": "Rate limit or monthly quota reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Quota": {
        "type": "object",
        "properties": {
          "used": { "type": "integer" },
          "limit": { "type": ["integer", "null"] },
          "remaining": { "type": ["integer", "null"] }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" }, "message": { "type": "string" } }
      },
      "WebResult": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "snippet": { "type": "string" },
          "domain": { "type": "string" },
          "language": { "type": "string" },
          "published_date": { "type": "string" },
          "type": { "type": "string" },
          "score": { "type": "number" }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "query": { "type": "string" },
          "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebResult" } },
          "answer": { "description": "Answer card from an official open source, when one fits the query" },
          "quota": { "$ref": "#/components/schemas/Quota" }
        }
      },
      "Article": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "image_url": { "type": "string" },
          "source_domain": { "type": "string" },
          "category": { "type": "string" },
          "country": { "type": "string" },
          "published_timestamp": { "type": "string" }
        }
      },
      "NewsSearchResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "query": { "type": "string" },
          "country": { "type": ["string", "null"] },
          "topic": { "type": ["string", "null"] },
          "days": { "type": "integer" },
          "count": { "type": "integer" },
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } },
          "quota": { "$ref": "#/components/schemas/Quota" }
        }
      },
      "HeadlinesResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "count": { "type": "integer" },
          "articles": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } },
          "quota": { "$ref": "#/components/schemas/Quota" }
        }
      },
      "ExtractResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "url": { "type": "string" },
          "final_url": { "type": "string" },
          "title": { "type": "string" },
          "authors": { "type": "array", "items": { "type": "string" } },
          "published": { "type": ["string", "null"] },
          "image": { "type": ["string", "null"] },
          "text": { "type": "string" },
          "length": { "type": "integer" },
          "truncated": { "type": "boolean" },
          "quota": { "$ref": "#/components/schemas/Quota" }
        }
      },
      "ListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "results": { "type": "array", "items": { "type": "object" } },
          "pagination": { "type": "object" },
          "filters": { "type": "object" },
          "quota": { "$ref": "#/components/schemas/Quota" }
        }
      }
    }
  }
}