{
  "openapi": "3.0.3",
  "info": {
    "title": "AtlasSERP API",
    "version": "1.0.0",
    "description": "High-Performance, Real-Time Google Search API for AI Agents, LLMs, and Developers. Delivers clean, structured JSON with sub-480ms latency.",
    "contact": {
      "name": "AtlasSERP Support",
      "url": "https://atlasserp.com",
      "email": "support@atlasserp.com"
    }
  },
  "servers": [
    {
      "url": "https://atlasserp.com",
      "description": "AtlasSERP Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "Your AtlasSERP API key from https://atlasserp.com/dashboard"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/search": {
      "post": {
        "summary": "Google Web Search",
        "description": "Execute real-time Google web search queries and retrieve parsed organic results, knowledge graph, answer box, and related questions.",
        "operationId": "searchWeb",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "example": "best coffee beans",
                    "description": "Search query string"
                  },
                  "gl": {
                    "type": "string",
                    "example": "us",
                    "default": "us",
                    "description": "Two-letter country code for geographic targeting"
                  },
                  "hl": {
                    "type": "string",
                    "example": "en",
                    "default": "en",
                    "description": "Two-letter language code"
                  },
                  "page": {
                    "type": "integer",
                    "example": 1,
                    "default": 1,
                    "description": "Page number"
                  },
                  "num": {
                    "type": "integer",
                    "example": 10,
                    "default": 10,
                    "description": "Number of results to return (10-100)"
                  },
                  "autocorrect": {
                    "type": "boolean",
                    "example": true,
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Google SERP response in clean JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchParameters": {
                      "type": "object"
                    },
                    "organic": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "link": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          },
                          "position": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "credits": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "402": {
            "description": "Insufficient credits"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/images": {
      "post": {
        "summary": "Google Images Search",
        "description": "Retrieve real-time Google Images search results.",
        "operationId": "searchImages",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "example": "electric sports cars"
                  },
                  "gl": {
                    "type": "string",
                    "default": "us"
                  },
                  "hl": {
                    "type": "string",
                    "default": "en"
                  },
                  "page": {
                    "type": "integer",
                    "default": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Images search results"
          }
        }
      }
    },
    "/news": {
      "post": {
        "summary": "Google News Search",
        "description": "Retrieve real-time Google News articles with publishers, dates, and snippets.",
        "operationId": "searchNews",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "example": "artificial intelligence breakthroughs"
                  },
                  "gl": {
                    "type": "string",
                    "default": "us"
                  },
                  "hl": {
                    "type": "string",
                    "default": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "News search results"
          }
        }
      }
    },
    "/places": {
      "post": {
        "summary": "Google Maps / Places Search",
        "description": "Retrieve Google Maps local business data, ratings, reviews count, address, and phone numbers.",
        "operationId": "searchPlaces",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "example": "italian restaurants in new york"
                  },
                  "gl": {
                    "type": "string",
                    "default": "us"
                  },
                  "hl": {
                    "type": "string",
                    "default": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Places local search results"
          }
        }
      }
    },
    "/videos": {
      "post": {
        "summary": "Google Videos Search",
        "description": "Retrieve Google Videos search results with channels, duration, and timestamps.",
        "operationId": "searchVideos",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "q"
                ],
                "properties": {
                  "q": {
                    "type": "string",
                    "example": "machine learning course"
                  },
                  "gl": {
                    "type": "string",
                    "default": "us"
                  },
                  "hl": {
                    "type": "string",
                    "default": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Videos search results"
          }
        }
      }
    },
    "/scrape": {
      "post": {
        "summary": "Universal Webpage Scraper & Markdown Extractor",
        "description": "Scrape and extract clean textual content, markdown, and metadata from any public URL for LLM and RAG pipelines.",
        "operationId": "scrapeUrl",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "example": "https://example.com/article",
                    "description": "Target webpage URL to scrape"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Clean parsed webpage content, markdown, and metadata"
          },
          "400": {
            "description": "Missing or invalid URL"
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    }
  }
}