{
  "openapi": "3.1.0",
  "info": {
    "title": "link.sc API",
    "version": "1.0.0",
    "description": "Web fetch and search API optimized for LLMs.\n\nExtract clean markdown from any URL or search the web with structured SERP results.\n\n## Getting Started\n\n1. Create an account at [link.sc](https://link.sc/register)\n2. Generate an API key from [your dashboard](https://link.sc/dashboard/keys)\n3. Include your key in the `x-api-key` header with every request\n\n## Features\n\n- **Fetch any URL** — Returns cleaned markdown, HTML, or JSON\n- **Web Search** — Google and Bing with structured SERP parsing\n- **SERP Data** — Organic results, ads, shopping, People Also Ask\n- **Auto-detection** — Fetching a Google/Bing URL automatically returns parsed SERP data\n- **LLM-optimized** — Markdown output reduces tokens by 85-90%\n\n## Rate Limits\n\nFree tier: 500 requests/month. Upgrade at [link.sc/dashboard/billing](https://link.sc/dashboard/billing).",
    "contact": {
      "url": "https://link.sc"
    }
  },
  "servers": [
    { "url": "https://api.link.sc/v1", "description": "Production" },
    { "url": "http://localhost:3000/v1", "description": "Local" }
  ],
  "security": [{ "apiKey": [] }],
  "x-tagGroups": [
    {
      "name": "Endpoints",
      "tags": ["Core"]
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your link.sc API key (starts with `lsc_`). Create one at [link.sc/dashboard/keys](https://link.sc/dashboard/keys)."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Error code", "example": "MISSING_URL" },
          "message": { "type": "string", "description": "Human-readable error message", "example": "API key required" }
        }
      },
      "SerpResult": {
        "type": "object",
        "description": "An organic search result from the SERP.",
        "properties": {
          "title": { "type": "string", "example": "NVIDIA Reports Record Q4 Revenue" },
          "targetUrl": { "type": "string", "format": "uri", "example": "https://nvidianews.nvidia.com/news/q4-fiscal-2025" },
          "description": { "type": "string", "example": "NVIDIA reported record quarterly revenue of $39.3 billion, up 12% from Q3 and up 78% year-over-year." },
          "realPosition": { "type": "integer", "example": 1 }
        }
      },
      "SerpAd": {
        "type": "object",
        "description": "A paid advertisement result from the SERP.",
        "properties": {
          "title": { "type": "string", "example": "NVIDIA Official Store" },
          "displayUrl": { "type": "string", "example": "store.nvidia.com" },
          "targetUrl": { "type": "string", "format": "uri", "example": "https://store.nvidia.com" },
          "content": { "type": "string", "example": "Shop the latest GPUs, gaming laptops, and AI hardware." },
          "position": { "type": "integer", "example": 1 },
          "realPosition": { "type": "integer", "example": 1 },
          "area": { "type": "string", "enum": ["top", "bottom"], "example": "top" }
        }
      },
      "SerpShoppingAd": {
        "type": "object",
        "description": "A shopping/product result from the SERP.",
        "properties": {
          "title": { "type": "string", "example": "NVIDIA GeForce RTX 5090" },
          "price": { "type": "string", "example": "$1,999.00" },
          "originalPrice": { "type": "string", "nullable": true, "example": "$2,199.00" },
          "advertiser": { "type": "string", "example": "Best Buy" },
          "targetUrl": { "type": "string", "format": "uri" },
          "image": { "type": "string", "format": "uri" },
          "discountText": { "type": "string", "example": "9% off" }
        }
      },
      "PeopleAlsoAsk": {
        "type": "object",
        "description": "A related question from the SERP \"People Also Ask\" section.",
        "properties": {
          "question": { "type": "string", "example": "What was NVIDIA's revenue in Q4 2025?" },
          "position": { "type": "integer", "example": 1 }
        }
      },
      "SerpData": {
        "type": "object",
        "description": "Structured SERP (Search Engine Results Page) data. Returned when fetching Google/Bing URLs or using the search endpoint.",
        "properties": {
          "results": {
            "type": "array",
            "description": "Organic search results",
            "items": { "$ref": "#/components/schemas/SerpResult" }
          },
          "ads": {
            "type": "array",
            "description": "Paid advertisement results",
            "items": { "$ref": "#/components/schemas/SerpAd" }
          },
          "adsCount": { "type": "integer", "description": "Total number of ads detected", "example": 2 },
          "shoppingAds": {
            "type": "array",
            "description": "Shopping/product ads",
            "items": { "$ref": "#/components/schemas/SerpShoppingAd" }
          },
          "peopleAlsoAsk": {
            "type": "array",
            "description": "Related questions from the SERP",
            "items": { "$ref": "#/components/schemas/PeopleAlsoAsk" }
          },
          "location": {
            "type": "object",
            "description": "Detected location metadata from the search engine",
            "properties": {
              "country": { "type": "string", "example": "United States" },
              "htmlLang": { "type": "string", "example": "en" },
              "region": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/fetch": {
      "post": {
        "operationId": "fetch",
        "summary": "Fetch a URL",
        "description": "Fetch content from any web page. Returns cleaned markdown optimized for LLM consumption.\n\nWhen the target URL is a Google or Bing search page, the response automatically includes parsed `serpData` with structured results.",
        "tags": ["Core"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The URL to fetch"
                  },
                  "format": {
                    "type": "string",
                    "enum": ["markdown", "html", "json"],
                    "default": "markdown",
                    "description": "Output format for the response content"
                  }
                }
              },
              "examples": {
                "Fetch a webpage": {
                  "summary": "Fetch a webpage as markdown",
                  "value": {
                    "url": "https://example.com",
                    "format": "markdown"
                  }
                },
                "Fetch as HTML": {
                  "summary": "Fetch raw HTML",
                  "value": {
                    "url": "https://news.ycombinator.com",
                    "format": "html"
                  }
                },
                "Fetch a Google SERP": {
                  "summary": "Fetch a Google search page (auto-parses SERP)",
                  "value": {
                    "url": "https://www.google.com/search?q=nvidia+earnings",
                    "format": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully fetched content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "url": { "type": "string" },
                    "format": { "type": "string" },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "title": { "type": "string" },
                        "description": { "type": "string" },
                        "language": { "type": "string" }
                      }
                    },
                    "markdown": { "type": "string", "description": "Cleaned markdown content" },
                    "content": { "type": "string", "description": "Raw HTML (when format=html)" },
                    "serpData": {
                      "$ref": "#/components/schemas/SerpData"
                    },
                    "searchEngine": {
                      "type": "string",
                      "enum": ["google", "bing"],
                      "description": "Present when a SERP page was detected and parsed"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "cost": { "type": "integer" },
                        "remaining": { "type": "integer" }
                      }
                    }
                  }
                },
                "examples": {
                  "Webpage response": {
                    "summary": "Markdown response from a webpage",
                    "value": {
                      "success": true,
                      "url": "https://example.com",
                      "format": "markdown",
                      "metadata": {
                        "title": "Example Domain",
                        "description": "This domain is for use in illustrative examples.",
                        "language": "en"
                      },
                      "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples in documents...",
                      "usage": { "cost": 1, "remaining": 499 }
                    }
                  },
                  "SERP response": {
                    "summary": "Auto-detected Google SERP with parsed data",
                    "value": {
                      "success": true,
                      "url": "https://www.google.com/search?q=nvidia+earnings",
                      "searchEngine": "google",
                      "serpData": {
                        "results": [
                          {
                            "title": "NVIDIA Reports Record Q4 Revenue",
                            "targetUrl": "https://nvidianews.nvidia.com/news/q4-fiscal-2025",
                            "description": "NVIDIA reported record quarterly revenue of $39.3 billion, up 78% year-over-year.",
                            "realPosition": 1
                          },
                          {
                            "title": "NVIDIA Corporation (NVDA) Earnings Report",
                            "targetUrl": "https://finance.yahoo.com/quote/NVDA/",
                            "description": "Get the latest NVIDIA earnings results, analyst forecasts, and financial data.",
                            "realPosition": 2
                          }
                        ],
                        "ads": [],
                        "adsCount": 0,
                        "shoppingAds": [],
                        "peopleAlsoAsk": [
                          { "question": "What was NVIDIA's revenue in Q4 2025?", "position": 1 },
                          { "question": "When is NVIDIA's next earnings call?", "position": 2 }
                        ],
                        "location": { "country": "United States", "htmlLang": "en" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing URL",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "MISSING_URL", "message": "URL is required" } } }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "UNAUTHORIZED", "message": "API key required" } } }
          },
          "403": {
            "description": "Quota exceeded",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "QUOTA_EXCEEDED", "message": "Monthly quota exceeded. Upgrade at link.sc/dashboard/billing" } } }
          },
          "502": {
            "description": "Fetch failed",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "EXTRACTION_FAILED", "message": "The link.sc engine encountered an error while retrieving data." } } }
          }
        }
      }
    },
    "/search": {
      "post": {
        "operationId": "search",
        "summary": "Web search",
        "description": "Search the web using Google or Bing and return structured SERP results.\n\nReturns organic results, paid ads, shopping ads, and People Also Ask questions in a single structured response.",
        "tags": ["Core"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["q"],
                "properties": {
                  "q": {
                    "type": "string",
                    "description": "Search query"
                  },
                  "engine": {
                    "type": "string",
                    "enum": ["google", "bing"],
                    "default": "google",
                    "description": "Search engine to use"
                  },
                  "format": {
                    "type": "string",
                    "enum": ["markdown", "html", "json"],
                    "default": "markdown",
                    "description": "Output format for the response content"
                  }
                }
              },
              "examples": {
                "Google search": {
                  "summary": "Search Google",
                  "value": {
                    "q": "latest NVIDIA earnings",
                    "engine": "google"
                  }
                },
                "Bing search": {
                  "summary": "Search Bing",
                  "value": {
                    "q": "best web scraping APIs 2026",
                    "engine": "bing"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "content": { "type": "string", "description": "Raw HTML content from the search page" },
                    "serpData": {
                      "$ref": "#/components/schemas/SerpData"
                    },
                    "searchEngine": {
                      "type": "string",
                      "enum": ["google", "bing"],
                      "description": "The search engine that was used"
                    }
                  }
                },
                "examples": {
                  "Search results": {
                    "summary": "Google search results with SERP data",
                    "value": {
                      "searchEngine": "google",
                      "serpData": {
                        "results": [
                          {
                            "title": "NVIDIA Reports Record Q4 Revenue of $39.3B",
                            "targetUrl": "https://nvidianews.nvidia.com/news/q4-fiscal-2025",
                            "description": "NVIDIA today reported record revenue of $39.3 billion for the fourth quarter ended January 26, 2025, up 12% from Q3 and up 78% from a year ago.",
                            "realPosition": 1
                          },
                          {
                            "title": "NVDA Earnings: What to Watch",
                            "targetUrl": "https://finance.yahoo.com/news/nvda-earnings",
                            "description": "Analysts expect NVIDIA to report EPS of $0.85 on revenue of $38.2 billion for Q4 2025.",
                            "realPosition": 2
                          },
                          {
                            "title": "NVIDIA Q4 2025 Earnings Call Transcript",
                            "targetUrl": "https://seekingalpha.com/article/nvidia-q4-2025-earnings",
                            "description": "Read the full transcript of NVIDIA's Q4 2025 earnings conference call.",
                            "realPosition": 3
                          }
                        ],
                        "ads": [
                          {
                            "title": "Invest in NVDA | Trade NVIDIA Stock",
                            "displayUrl": "www.etrade.com/nvda",
                            "targetUrl": "https://www.etrade.com/nvda",
                            "content": "Trade NVIDIA with zero commission. Open an account today.",
                            "position": 1,
                            "realPosition": 1,
                            "area": "top"
                          }
                        ],
                        "adsCount": 1,
                        "shoppingAds": [],
                        "peopleAlsoAsk": [
                          { "question": "What was NVIDIA's revenue in Q4 2025?", "position": 1 },
                          { "question": "Is NVIDIA stock a buy after earnings?", "position": 2 },
                          { "question": "When is NVIDIA's next earnings date?", "position": 3 }
                        ],
                        "location": {
                          "country": "United States",
                          "htmlLang": "en"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing query",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "MISSING_QUERY", "message": "Search query is required" } } }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "UNAUTHORIZED", "message": "API key required" } } }
          },
          "403": {
            "description": "Quota exceeded",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "QUOTA_EXCEEDED", "message": "Monthly quota exceeded. Upgrade at link.sc/dashboard/billing" } } }
          }
        }
      }
    }
  }
}