# ServerSearcher — API reference for AI agents

Base URL: https://www.serversearcher.com

## Plain-text search (recommended for LLMs)

```bash
curl -s "https://www.serversearcher.com/api/hostingsearch/search?format=text&type=dedicated&sortConfig=priceAsc&pageSize=20"

curl -s "https://www.serversearcher.com/api/hostingsearch/search?format=text&type=dedicated&maxPrice=200&minRam=32"
```

Response is UTF-8 plain text with:
- Active filters echoed at the top
- Total match count
- Each plan with provider page and affiliate checkout URLs

## JSON search API

```bash
curl -s "https://www.serversearcher.com/api/hostingsearch/search?type=dedicated&maxPrice=200&pageSize=20"

curl -s -X POST "https://www.serversearcher.com/api/hostingsearch/search" \
  -H "Content-Type: application/json" \
  -d '{"type":["dedicated"],"maxPrice":"200","pageSize":20,"sortConfig":"priceAsc"}'
```

## HTML search results table (secondary)

The page `GET /servers/search/?type=dedicated&maxPrice=200` server-renders a
`<table id="server-search-crawler-results">` containing the first page of matching
plans (provider, plan, specs, location, monthly price). The table is in the HTML of
every request — no JavaScript is required to read it — and query parameters change
the server-rendered output. Use the `format=text` API above when you need more than
the first page.

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| format | string | Set to `text` for plain-text responses (GET only) |
| type | string[] | Plan types: `dedicated`, `virtual`, `cloud`, etc. |
| minRam | string | Minimum RAM (GB) |
| minCpuCores | string | Minimum CPU cores |
| cpuModel | string | CPU model substring (e.g. `EPYC`); `*` and `?` are wildcards |
| maxPrice | string | Maximum monthly price |
| location | string[] | City UUID, country code (e.g. `US`), or `US-new-york` |
| provider | string[] | Provider IDs |
| sortConfig | string | `priceAsc`, `priceDesc`, `ramAsc`, `ramDesc`, `cpuAsc`, `cpuDesc`, … |
| page | number | Page number (default 1) |
| pageSize | number | Results per page (default 50, max 150) |
| hasTerraform | boolean | `true` to filter Terraform-supported providers |

## JSON response shape

Both the GET and POST forms of `/api/hostingsearch/search` return the same object:

```json
{
  "plans": [
    {
      "id": "…",
      "name": "…",
      "description": "…",
      "type": "dedicated",
      "cpuCores": 8,
      "cpuThreads": 16,
      "cpuModel": "…",
      "cpuFrequency": 3.4,
      "ram": 64,
      "includedBandwidthQuota": 20,
      "portSpeed": 1000,
      "secondPortSpeed": null,
      "additionalDetails": null,
      "directPlanUrl": "…",
      "minMonthlyCostUsd": 129.0,
      "pricePerRamUsd": 2.02,
      "pricePerCpuUsd": 16.13,
      "pricePerRamCpuUsd": 0.25,
      "disks": [{ "id": "…", "capacity": 960, "type": "NVME" }],
      "gpus": [
        {
          "id": "…",
          "model": "…",
          "count": 1,
          "vRAM": 24,
          "architecture": "…",
          "cudaCores": 10752
        }
      ],
      "pricing": [
        {
          "id": "…",
          "monthlyCost": 119.0,
          "hourlyCost": null,
          "currency": "EUR",
          "minimumTerm": 1,
          "setupFee": null,
          "billingCycle": "MONTHLY",
          "usd": {
            "amount": 129.0,
            "rate": 0.92,
            "rateAt": "…",
            "fetchedAt": "…",
            "source": "…"
          }
        }
      ],
      "locations": [
        {
          "locationId": "…",
          "qty": 4,
          "name": "…",
          "cityId": "…",
          "city": "Amsterdam",
          "countryIso": "NL",
          "countryName": "Netherlands",
          "facility": null
        }
      ],
      "promoCodes": [
        {
          "id": "…",
          "code": "…",
          "discountAmount": 50,
          "discountType": "…",
          "currency": "USD",
          "credit": null,
          "description": "…",
          "expiresAt": "…"
        }
      ],
      "provider": {
        "id": "…",
        "name": "…",
        "slug": "…",
        "logo": "…",
        "website": "…",
        "terraformProvider": "OFFICIAL"
      }
    }
  ],
  "totalResults": 412,
  "page": 1,
  "pageSize": 50,
  "searchId": "…",
  "exchangeRatesAvailable": true
}
```

`totalResults` is the count before pagination, so `Math.ceil(totalResults / pageSize)`
is the number of pages. `minMonthlyCostUsd` and the three `pricePer*Usd` fields are
normalised to USD and are the values the site sorts on; `exchangeRatesAvailable` is
`false` when the latest FX read failed, in which case those fields may be stale.

## MCP

Endpoint: `https://www.serversearcher.com/api/mcp`
Tool: `search_servers` with the same filter fields as the JSON API. The `provider`
filter additionally accepts org slugs (e.g. `runpod`), resolved server-side —
the JSON API itself takes provider ids only. `type` includes `gpu` here too.