# UpSnatch API and MCP

Last updated: October 2026

Search the UpSnatch domain catalog from your own scripts, or let Claude, ChatGPT, Cursor, Windsurf, Claude Code, Gemini CLI, Codex CLI, VS Code, and other AI agents search it for you.

HTML version: [https://upsnatch.com/developers/](https://upsnatch.com/developers/)

## Table of contents

- [Overview](#overview)
- [REST API](#rest-api)
  - [Quick start](#quick-start)
  - [Authentication](#authentication)
  - [Search domains](#search-domains)
  - [Get one domain](#get-one-domain)
  - [Response fields](#response-fields)
  - [Rate limits and quotas](#rate-limits-and-quotas)
  - [Errors](#errors)
  - [OpenAPI specification](#openapi-specification)
- [MCP](#mcp)
  - [Claude connector](#claude-connector)
  - [ChatGPT plugin](#chatgpt-plugin)
  - [Developer tools (API key)](#developer-tools-api-key)
    - [Cursor](#cursor)
    - [Windsurf](#windsurf)
    - [Claude Code](#claude-code)
    - [Gemini CLI](#gemini-cli)
    - [Codex CLI](#codex-cli)
    - [VS Code](#vs-code)
  - [Other tools and IDEs](#other-tools-and-ides)

## Overview

The UpSnatch API gives you the same catalog as Classic Search in the app: expired, dropped, pending-delete, auction, and marketplace domains with SEO metrics such as Majestic Trust Flow and Citation Flow, backlinks, referring domains, Ahrefs DR, age, and price.

- **[REST API](#rest-api)** at `https://api.upsnatch.com` for scripts, spreadsheets, and CRMs. Auth is an API key.
- **[MCP](#mcp)** at `https://api.upsnatch.com/mcp` for AI agents. Claude and ChatGPT sign in with OAuth; Cursor, Windsurf, Claude Code, Gemini CLI, Codex CLI, and VS Code use an API key.

REST and MCP share the same rate limits and row quota. API access is included in [all paid plans](https://upsnatch.com/pricing.html). Explorer comes with 1,000 result rows per week so you can try it in your own tools; Pro and Agency have daily allowances for real workloads.

**What the API covers today:** Keyword and metric search (Classic Search) and single-domain lookups. Magic Search, Local Search, and Projects are not available through the API yet.

## REST API

HTTP endpoints for your own code. Base URL: `https://api.upsnatch.com`. Every request uses a Bearer API key from [Settings, API access](https://app.upsnatch.com/settings/api).

### Quick start

1. Open [Settings, API access](https://app.upsnatch.com/settings/api) in the app and generate a key. It starts with `ups_live_` and is shown only once.
2. Send it as a Bearer token:

```bash
curl -X POST "https://api.upsnatch.com/v1/search/classic?page=1&page_size=25" \
  -H "Authorization: Bearer $UPSNATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "coffee", "tlds": ["com"], "minTrustFlow": 10}'
```

The response contains one page of domains plus pagination fields:

```json
{
  "results": [
    {
      "domain": "coffeeandbooks.com",
      "tld": "com",
      "type": "MARKETPLACE",
      "available": true,
      "provider": "nameshift",
      "price": 14995,
      "currency": "USD",
      "trustFlow": 16,
      "citationFlow": 11,
      "tfCfRatio": 1.45,
      "backlinks": 46,
      "referringDomains": 29,
      "ahrefsDr": 4,
      "score": 75,
      "spamRisk": "low",
      "purchaseUrl": "https://app.upsnatch.com/go/coffeeandbooks.com"
    }
  ],
  "page": 1,
  "page_size": 25,
  "returned": 25,
  "total": 98,
  "has_more": true
}
```

### Authentication

Every REST request needs your key in the `Authorization` header: `Authorization: Bearer ups_live_…`. Each account has one key. Generating a new key replaces the old one immediately.

**Keep your key secret.** Call the API from your own server, scripts, or local tools only. Never put the key in browser JavaScript, mobile apps, or public repositories: anyone who can read it can use your quota. If a key leaks, generate a new one in Settings and the old key stops working right away.

The key follows your subscription. If a payment fails or the subscription ends, requests return `403 subscription_inactive`, and the same key works again as soon as the subscription is active.

### Search domains

`POST /v1/search/classic?page=1&page_size=25`

Send filters as a JSON body. At least one selective filter is required: a keyword of 2 or more characters, `tlds`, `listingTypes`, a price range, or a `min…` metric above 0. Unknown fields are rejected, so a typo never silently widens your search.

| Field | Meaning |
| --- | --- |
| `keyword` | Word or phrase the name must contain. Plurals are matched too. Up to 100 characters. |
| `listingTypes` | Any of `AUCTION`, `DROPPED`, `MARKETPLACE`, `PENDING_DELETE`. |
| `tlds` | Extensions without the dot, for example `["com", "nl"]`. Up to 50. |
| `marketTlds` | Only names whose label is also registered as a site on these extensions. |
| `minTrustFlow`, `minCitationFlow` | Minimum Majestic Trust Flow and Citation Flow (0 to 100). |
| `minTfCfRatio` | Minimum Trust Flow divided by Citation Flow, for example `0.5`. |
| `minBacklinks`, `minRefDomains` | Minimum backlinks and referring domains. |
| `minAhrefsDr` | Minimum Ahrefs Domain Rating (0 to 100). |
| `minIndexed`, `minPageviews` | Minimum indexed URLs and pageviews. |
| `minValuation` | Minimum estimated value in USD. |
| `priceFrom`, `priceTo` | Price range in USD. |
| `minBids` | Minimum number of auction bids. |
| `availability` | `today` or `thisweek`: auctions ending in that window. |
| `minAge` | Minimum domain age in years. |
| `minLength`, `maxLength` | Length of the name without the extension. |
| `minSegments` | Minimum number of words in the name. |
| `language` | Language of the name, for example `en`, `nl`, `de`. |
| `excludeAdult` | Hide adult names. Defaults to `true`. |
| `excludeHyphens` | Hide names with hyphens. |
| `numbersMode` | `ANY`, `NO_DIGITS`, or `DIGITS_ONLY`. |

#### Pagination

`page` starts at 1. `page_size` defaults to 25 and goes up to 50 on Pro and 100 on Agency. Keep requesting the next page while `has_more` is `true`. `page` × `page_size` may not exceed 2,000 on Pro or 5,000 on Agency; narrow your filters to reach results beyond that.

### Get one domain

`GET /v1/domains/{domain}`

```bash
curl "https://api.upsnatch.com/v1/domains/coffeeandbooks.com" \
  -H "Authorization: Bearer $UPSNATCH_API_KEY"
```

Returns the same fields as a search result, or `404 not_found` when the domain is not in the catalog. Unlike search, a lookup can also return listings that were sold or auctions that ended; check `available`. Internationalized names can be sent in Unicode or punycode.

### Response fields

Fields without data are `null`.

| Field | Meaning |
| --- | --- |
| `domain`, `tld` | The name and its extension. |
| `type` | `AUCTION`, `DROPPED`, `MARKETPLACE`, or `PENDING_DELETE`. |
| `available` | Whether the listing can still be bought: marketplace listing not sold, auction not ended, dropped domain not registered again. |
| `provider` | Auction or marketplace platform, for example `godaddy`. `null` for dropped domains. |
| `price`, `currency` | Current price or bid, always in USD. |
| `numberOfBids`, `auctionEndTime` | Auction bid count and end time (ISO 8601). `null` for other types. |
| `trustFlow`, `citationFlow`, `tfCfRatio` | Majestic metrics and their ratio. |
| `backlinks`, `referringDomains`, `ahrefsDr` | Link metrics. UpSnatch's own enrichment is used first, the platform's data otherwise. |
| `domainAge`, `indexedURLs`, `domainLength` | Age in years, indexed URLs, and length of the name. |
| `score` | UpSnatch quality score from 0 to 100. Spam is not part of the score; check `spamRisk` alongside it. |
| `spamRisk` | `low`, `medium`, `high`, or `unknown` when there is not enough link data. |
| `availabilityStatus`, `availabilityCheckedAt` | Last registration check for dropped domains. |
| `purchaseUrl` | Link to buy or bid on the domain. Use this link rather than building marketplace URLs yourself. `null` when the domain is no longer available. |

See [Metrics and quality signals](https://upsnatch.com/docs/articles/metrics-quality-signals/) for how to read these numbers.

### Rate limits and quotas

REST calls and MCP tool calls count against the same limits.

| Limit | Explorer | Pro | Agency |
| --- | --- | --- | --- |
| Requests per minute | 30 | 30 | 90 |
| Requests per hour | 200 | 600 | 2,000 |
| Result rows | 1,000 per week | 20,000 per day | 50,000 per day |
| Requests at the same time | 1 | 1 | 2 |
| Maximum page size | 50 | 50 | 100 |
| Maximum depth (page × page_size) | 1,000 | 2,000 | 5,000 |

Every search counts as one request plus the number of rows it returns. A domain lookup counts as one request and no rows. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RowQuota-Limit`, and `X-RowQuota-Remaining` headers so you can pace your script. Daily allowances reset at 00:00 UTC; the Explorer weekly allowance resets on Monday at 00:00 UTC.

Use the API for your own research and tooling. Bulk-copying or redistributing the catalog to rebuild a competing dataset is not allowed under our [Terms of Use](https://upsnatch.com/terms.html); we may revoke keys when we detect abuse.

### Errors

Errors are JSON with an `error` code and a readable `message`.

| Status and code | What to do |
| --- | --- |
| `400 validation_error` | Fix the request. `details` lists each field with an issue such as `unknown_field` or `out_of_range`. |
| `401 unauthorized` | The key is missing, wrong, or was replaced by a newer one. |
| `403 forbidden` | Your plan does not include API access. |
| `403 subscription_inactive` | The subscription ended or a payment failed. The key works again once the subscription is active. |
| `404 not_found` | The domain is not in the catalog, or the path does not exist. |
| `429 rate_limited` | Wait `retry_after_seconds` (also in the `Retry-After` header). `class` says which limit you hit: `rate`, `row_quota`, or `concurrent`. |
| `503 service_busy` | Search capacity is briefly exhausted. Retry after a few seconds. |
| `502 search_failed` | Temporary problem on our side. Retry later. |

Validation errors are checked before any quota is used, except when no selective filter was given.

### OpenAPI specification

The full machine-readable description is at [api.upsnatch.com/openapi.yaml](https://api.upsnatch.com/openapi.yaml) (OpenAPI 3.0). Import it into Postman, Insomnia, or a code generator to get a typed client.

## MCP

The MCP server lets an AI agent search UpSnatch for you. Ask it things like "find .com auctions ending this week about coffee with Trust Flow above 15" and it picks the filters itself from the tool schema.

- **URL:** `https://api.upsnatch.com/mcp` (Streamable HTTP)
- **Tools:** `search_classic` and `get_domain`. Both are read-only and map to the REST endpoints above.

How you connect depends on the product:

- [Claude connector](#claude-connector) (claude.ai / Claude desktop): sign in with UpSnatch (OAuth). No API key.
- [ChatGPT plugin](#chatgpt-plugin): add a custom MCP server, then sign in with UpSnatch (OAuth). No API key.
- [Developer tools (API key)](#developer-tools-api-key): Cursor, Windsurf, Claude Code, Gemini CLI, Codex CLI, and VS Code. Claude Code is Anthropic's CLI, not the Claude chat connector above.
- [Other tools and IDEs](#other-tools-and-ides): any MCP client that can call a remote HTTP server with a Bearer header.

**Agents and quota:** Agents tend to search again and again. Every tool call uses the same quota as a REST call, so ask for small pages and specific filters, for example "10 results" rather than "everything".

### Claude connector

Add UpSnatch as a custom connector in Claude (web or desktop). You sign in with your UpSnatch account via the browser; Claude never sees an API key.

1. In Claude, open **Settings**, then **Connectors** (wording can vary slightly between web and desktop).
2. Add a custom connector. Use this MCP URL:

```
https://api.upsnatch.com/mcp
```

3. Complete the UpSnatch sign-in and click **Allow access** on the consent screen. Your plan must include API access (Explorer or higher).
4. Back in Claude, confirm the connector shows tools such as **Search expired domains** and **Get domain details**.
5. In a chat, ask something concrete, for example: *search expired domains with coffee, .com only, with some backlinks*. Approve the tool call when Claude asks.

Claude Free allows one custom connector at a time. Disconnect another connector first if you need the slot. For Anthropic's terminal CLI, see [Claude Code](#claude-code) under developer tools instead.

### ChatGPT plugin

In ChatGPT you add a **custom MCP server**; ChatGPT saves it as a **plugin**. Auth is OAuth (sign in with UpSnatch). Availability depends on your OpenAI plan: Business and Enterprise have full custom MCP; some Pro accounts can connect read-only MCP servers. Use ChatGPT on the web.

1. Open **Plugins** (or Apps), then **Add custom MCP server**.
2. Name it **UpSnatch**. Under Connection, choose **Server URL** and enter:

```
https://api.upsnatch.com/mcp
```

3. Set Authentication to **OAuth**. Leave Dynamic Client Registration (DCR) as discovered; ChatGPT should find `https://auth.upsnatch.com` automatically.
4. Accept the risk warning, choose **Create as a plugin**, then complete UpSnatch sign-in and **Allow access**.
5. Install or enable the plugin. In a new chat, type `@UpSnatch` (or select the plugin) and try: *search expired domains with coffee and some backlinks only .com and .net*.

If you do not see **Add custom MCP server**, your ChatGPT plan or workspace role does not allow custom MCP plugins yet.

### Developer tools (API key)

These tools send your UpSnatch API key as `Authorization: Bearer ups_live_…`. Create a key under [Settings, API access](https://app.upsnatch.com/settings/api). Prefer an environment variable called `UPSNATCH_API_KEY` over pasting the key into a shared config file.

Covered here: [Cursor](#cursor), [Windsurf](#windsurf), [Claude Code](#claude-code), [Gemini CLI](#gemini-cli), [Codex CLI](#codex-cli), and [VS Code](#vs-code).

#### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "upsnatch": {
      "url": "https://api.upsnatch.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UPSNATCH_API_KEY}"
      }
    }
  }
}
```

#### Windsurf

Windsurf Cascade reads `~/.codeium/windsurf/mcp_config.json` (open it from Cascade → MCP). Use `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "upsnatch": {
      "serverUrl": "https://api.upsnatch.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:UPSNATCH_API_KEY}"
      }
    }
  }
}
```

#### Claude Code

Anthropic's CLI (not the Claude chat connector). Add the server with your API key:

```bash
claude mcp add --transport http upsnatch https://api.upsnatch.com/mcp \
  --header "Authorization: Bearer $UPSNATCH_API_KEY"
```

#### Gemini CLI

Google's Gemini CLI. Prefer `httpUrl` for Streamable HTTP (plain `url` is for SSE). Either add via CLI:

```bash
gemini mcp add --transport http upsnatch https://api.upsnatch.com/mcp \
  --header "Authorization: Bearer $UPSNATCH_API_KEY"
```

Or put this under `mcpServers` in `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "upsnatch": {
      "httpUrl": "https://api.upsnatch.com/mcp",
      "headers": {
        "Authorization": "Bearer $UPSNATCH_API_KEY"
      }
    }
  }
}
```

#### Codex CLI

OpenAI's Codex CLI (terminal coding agent; for ChatGPT chat see [ChatGPT plugin](#chatgpt-plugin)). Add a remote server, then put the raw key (without `Bearer`) in the env var:

```bash
codex mcp add upsnatch \
  --url https://api.upsnatch.com/mcp \
  --bearer-token-env-var UPSNATCH_API_KEY
export UPSNATCH_API_KEY='ups_live_…'
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.upsnatch]
url = "https://api.upsnatch.com/mcp"
bearer_token_env_var = "UPSNATCH_API_KEY"
```

#### VS Code

Add this to `.vscode/mcp.json`. VS Code asks for the key once and stores it securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "upsnatch-key",
      "description": "UpSnatch API key",
      "password": true
    }
  ],
  "servers": {
    "upsnatch": {
      "type": "http",
      "url": "https://api.upsnatch.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:upsnatch-key}"
      }
    }
  }
}
```

### Other tools and IDEs

UpSnatch MCP is a standard Streamable HTTP server. It works with any client that can call `https://api.upsnatch.com/mcp` over HTTPS and authenticate with either:

- `Authorization: Bearer ups_live_…` (API key), or
- OAuth, when the client supports an MCP connector / sign-in flow

That includes Cline, Roo Code, Continue, Goose, Warp, JetBrains AI, LibreChat, and other MCP hosts, not only the apps with copy-paste configs above. They all get the same `search_classic` and `get_domain` tools.

If the product offers an OAuth or "sign in with UpSnatch" connector flow, prefer that over pasting an API key. Otherwise create a key under [Settings, API access](https://app.upsnatch.com/settings/api) and follow the client's docs for remote MCP + custom headers. Watch the URL field name: some clients use `url`, Windsurf uses `serverUrl`, and Gemini CLI uses `httpUrl`.