> ## Documentation Index
> Fetch the complete documentation index at: https://openrush.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool API reference

> Developer reference for `/v1/tools/*` endpoints.

If you use OpenRush through an AI agent, you do not need to memorize these tool names. Ask normal marketing questions and let your agent choose the right tool.

This page is for developers who call the REST API directly.

Tool endpoints require authentication. Send `Authorization: Bearer <key>` or `X-API-Key: <key>`.

Every successful tool response is an Open Fact Envelope. The `data` shape changes per tool, but the top-level envelope stays the same.

## Plain-language map

| If you want to...                              | Use this tool               |
| ---------------------------------------------- | --------------------------- |
| Understand one domain                          | `inspect_domain`            |
| Find search competitors                        | `discover_competitors`      |
| Find keyword ideas                             | `research_keywords`         |
| Find competitor keyword gaps                   | `compare_keyword_coverage`  |
| See today's Google results for a query         | `inspect_serp`              |
| Check where a site ranks for specific keywords | `inspect_search_visibility` |
| Audit a website for issues                     | `audit_site`                |
| Drill into one keyword                         | `inspect_keyword`           |
| Drill into one page                            | `inspect_page`              |
| Download full rows from a previous response    | `export_dataset`            |

## Inspect domain

`POST /v1/tools/inspect_domain`

Compact factual snapshot for one domain. Use this as the starting map for top keywords, top pages, estimated traffic, dominant intents, and likely competitors.

Credit cost: `3`

Request body:

| Field      | Type   | Required | Default         | Notes            |
| ---------- | ------ | -------- | --------------- | ---------------- |
| `domain`   | string | Yes      |                 | 2-253 characters |
| `location` | string | No       | `United States` | Market location  |
| `language` | string | No       | `English`       | Search language  |

Example:

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/inspect_domain" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'
```

`data` includes `domain`, `location`, `summary`, `top_keywords`, `top_pages`, `likely_competitors`, `intent_mix`, and optional `authority`.

## Discover competitors

`POST /v1/tools/discover_competitors`

Find organic competitors by domain overlap or by seed keywords.

Credit cost: `5`

Request body:

| Field           | Type      | Required | Default         | Notes                        |
| --------------- | --------- | -------- | --------------- | ---------------------------- |
| `domain`        | string    | No       |                 | Use for keyword-overlap mode |
| `seed_keywords` | string\[] | No       |                 | 1-20 seed queries            |
| `location`      | string    | No       | `United States` | Market location              |
| `language`      | string    | No       | `English`       | Search language              |
| `limit`         | integer   | No       | `10`            | 1-100                        |

Provide `domain` or `seed_keywords`. Domain mode is cheap and broad. Seed keyword mode works better for new or sparsely indexed sites.

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/discover_competitors" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed_keywords":["seo for ai agents","keyword gap api"],"limit":10}'
```

`data` includes `domain`, `location`, and `competitors`.

## Research keywords

`POST /v1/tools/research_keywords`

Expand a seed term into a ranked demand list.

Credit cost: `3`

Request body:

| Field        | Type    | Required | Default         | Notes                                                             |
| ------------ | ------- | -------- | --------------- | ----------------------------------------------------------------- |
| `seed`       | string  | Yes      |                 | 1-200 characters                                                  |
| `location`   | string  | No       | `United States` | Market location                                                   |
| `language`   | string  | No       | `English`       | Search language                                                   |
| `mode`       | string  | No       | `ideas`         | `ideas`, `suggestions`, or `related`                              |
| `limit`      | integer | No       | `25`            | 1-200                                                             |
| `min_volume` | integer | No       |                 | Minimum monthly volume                                            |
| `intent`     | string  | No       |                 | `informational`, `navigational`, `commercial`, or `transactional` |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/research_keywords" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed":"crm software","mode":"ideas","limit":25}'
```

`data` includes `seed`, `location`, `mode`, and `keywords`.

## Compare keyword coverage

`POST /v1/tools/compare_keyword_coverage`

Find keyword gaps where competitors rank and the target does not, plus keywords where the target is losing.

Credit cost: `5`

Request body:

| Field         | Type      | Required | Default         | Notes                   |
| ------------- | --------- | -------- | --------------- | ----------------------- |
| `domain`      | string    | Yes      |                 | Target domain           |
| `competitors` | string\[] | Yes      |                 | 1-10 competitor domains |
| `location`    | string    | No       | `United States` | Market location         |
| `language`    | string    | No       | `English`       | Search language         |
| `limit`       | integer   | No       | `50`            | 1-200                   |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/compare_keyword_coverage" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"pipedrive.com","competitors":["hubspot.com"],"limit":20}'
```

`data` includes `domain`, `location`, `competitors`, `gaps`, `losing`, and `intent_clusters`.

## Inspect SERP

`POST /v1/tools/inspect_serp`

Fetch a live SERP snapshot for one query.

Credit cost: `2`

Request body:

| Field      | Type    | Required | Default         | Notes            |
| ---------- | ------- | -------- | --------------- | ---------------- |
| `query`    | string  | Yes      |                 | 1-200 characters |
| `location` | string  | No       | `United States` | Market location  |
| `language` | string  | No       | `English`       | Search language  |
| `depth`    | integer | No       | `10`            | 10-100           |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/inspect_serp" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"best crm for startups","depth":10}'
```

`data` includes `query`, `location`, `fetched_at`, `item_types_present`, `organic`, optional `ai_overview`, `paid`, `local_pack`, optional `featured_snippet`, `people_also_ask`, and `related_searches`.

## Inspect search visibility

`POST /v1/tools/inspect_search_visibility`

Check where a domain ranks across a keyword set.

Credit cost: `3`

Request body:

| Field      | Type      | Required | Default         | Notes                      |
| ---------- | --------- | -------- | --------------- | -------------------------- |
| `domain`   | string    | Yes      |                 | Target domain              |
| `keywords` | string\[] | Yes      |                 | 1-100 keywords             |
| `location` | string    | No       | `United States` | Market location            |
| `language` | string    | No       | `English`       | Search language            |
| `mode`     | string    | No       | `auto`          | `auto`, `index`, or `live` |

`auto` tries the index first and falls back to live SERPs when the target is underindexed. `index` is fast and cheap. `live` reflects today's Google.

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/inspect_search_visibility" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"hubspot.com","keywords":["best crm for startups","crm software"]}'
```

`data` includes `domain`, `location`, `fetched_at`, `positions`, and `summary`.

## Audit site

`POST /v1/tools/audit_site`

Run a fast technical and content health audit over sampled pages.

Credit cost: `10`

Request body:

| Field       | Type    | Required | Default | Notes           |
| ----------- | ------- | -------- | ------- | --------------- |
| `domain`    | string  | Yes      |         | Domain to audit |
| `max_pages` | integer | No       | `10`    | 1-20            |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/audit_site" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com","max_pages":10}'
```

`data` includes `domain`, `discovery_source`, `pages_discovered`, `pages_audited`, `pages_excluded`, `fetch_failures`, `render_warning`, `templates_sampled`, `onpage_score`, `issues_summary`, `excluded_summary`, `page_class_summary`, `worst_page`, `recommendations`, `issue_clusters`, and compact `pages`.

Scope: the audit reads raw HTML. It does not execute JavaScript or measure Core Web Vitals.

## Inspect keyword

`POST /v1/tools/inspect_keyword`

Drill into one keyword.

Credit cost: `2`

Request body:

| Field      | Type   | Required | Default         | Notes            |
| ---------- | ------ | -------- | --------------- | ---------------- |
| `keyword`  | string | Yes      |                 | 1-200 characters |
| `location` | string | No       | `United States` | Market location  |
| `language` | string | No       | `English`       | Search language  |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/inspect_keyword" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"best crm for startups"}'
```

`data` includes `keyword`, `location`, `monthly_volume`, `cpc_usd`, `competition_level`, `intent`, `trend`, `serp_top`, and `serp_features`.

## Inspect page

`POST /v1/tools/inspect_page`

Drill into one exact URL.

Credit cost: `2`

Request body:

| Field      | Type   | Required | Default         | Notes             |
| ---------- | ------ | -------- | --------------- | ----------------- |
| `url`      | string | Yes      |                 | 8-2048 characters |
| `location` | string | No       | `United States` | Market location   |
| `language` | string | No       | `English`       | Search language   |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/inspect_page" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://stripe.com/payments"}'
```

`data` includes `url`, `location`, `organic_keywords`, `estimated_organic_traffic_per_month`, and `top_keywords`.

## Export dataset

`POST /v1/tools/export_dataset`

Fetch a full dataset by URI from a previous response `resources` entry.

Credit cost: `0`

Request body:

| Field | Type   | Required | Default | Notes                                                   |
| ----- | ------ | -------- | ------- | ------------------------------------------------------- |
| `uri` | string | Yes      |         | 8-512 characters. Must be a valid OpenRush dataset URI. |

```bash theme={null}
curl -X POST "https://api.openrush.io/v1/tools/export_dataset" \
  -H "Authorization: Bearer $OPENRUSH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uri":"openrush://dataset/..."}'
```

`data` includes `uri`, `items`, `available`, and optional `note`.

## Optional backlink tools

Some accounts may have backlink tools enabled. Check `/v1/capabilities` before calling them.

| Endpoint                              | Credits | Purpose                                                     |
| ------------------------------------- | ------: | ----------------------------------------------------------- |
| `POST /v1/tools/inspect_backlinks`    |       4 | Link profile, authority, referring domains, and anchors     |
| `POST /v1/tools/compare_backlink_gap` |       5 | Referring domains linking to competitors but not the target |

If these tools are not returned by `/v1/capabilities`, do not call them.