# API reference

Reach Dog is a low-cost product-data API. Send product titles and get back structured JSON: product type, brand, attributes, missing facts, Google product category, collections, search phrases with volume and cost per click, and buyer questions. Use it for the catalog grunt work, then give the JSON to your own model (Claude, GPT, Grok or any other) so its tokens go to the deeper analysis instead of extracting product facts. The JSON is keyed by the fields you asked for, so you can save it in your project and reuse it.

## At a glance

| Item | Detail |
|---|---|
| Base URL | `https://api.reach.dog` |
| Authentication | `Authorization: Bearer <REACHDOG_API_KEY>`, plus an `Idempotency-Key` on every creation request |
| Input | English product titles. One title per request, or 1-500 titles per catalog call (`POST /v1/batches`) |
| Output | JSON containing exactly the fields you requested, as top-level keys. Attributes come only from the title and any description or attributes you send; request `missing_attributes` to get the facts the title leaves out. Shopping associations such as categories, use cases and audiences need not appear in the title |
| Fields | 68 across title, research, content and catalog requests. See [Parameter reference](parameter-reference) |
| Price | Each requested field is priced per title, currently 25 Reach Dog tokens. Your account's live price is `parameter_price` in `GET /v1/usage`. A catalog output is priced once per call, regardless of title count. Free daily top-up |
| Tokens | Reach Dog tokens are billing units, not model tokens |
| OpenAPI | [api.reach.dog/openapi.json](https://api.reach.dog/openapi.json), interactive at [api.reach.dog/docs](https://api.reach.dog/docs) |

## Quickstart in Python

Create a key on the API keys page with the `match` scope, then set `REACHDOG_API_KEY` in your environment.

```python
import json, os, uuid
import requests

# Keep this key. Retrying this exact request with the same key never charges twice.
idempotency_key = str(uuid.uuid4())

response = requests.post(
    "https://api.reach.dog/v1/title-matches",
    headers={
        "Authorization": f"Bearer {os.environ['REACHDOG_API_KEY']}",
        "Idempotency-Key": idempotency_key,
        "Content-Type": "application/json",
    },
    json={
        "title": "Nordic Kayaks NK K1 Kayak",
        "parameters": ["product_type", "brand", "missing_attributes", "search_volume"],
    },
    timeout=60,
)
response.raise_for_status()

# Save the result once and reuse it in your own prompts.
with open("reachdog_result.json", "w") as f:
    json.dump(response.json(), f, indent=2)
```

The response has one top-level key per requested field, for example `"product_type": "Kayak"` and `"brand": "Nordic Kayaks"`. Four fields at the current price cost 100 Reach Dog tokens.

## Ready-made code on GitHub

| What | Where |
|---|---|
| Python and JavaScript examples | [github.com/reachdog/title-cluster-api-examples](https://github.com/reachdog/title-cluster-api-examples) |
| MCP server for Claude Desktop and other MCP clients | [github.com/reachdog/reachdog-mcp](https://github.com/reachdog/reachdog-mcp) (`npx --yes @reachdog/mcp@0.1.0`) |
| LangChain tools with a budget and approval step | [github.com/reachdog/langchain-reachdog](https://github.com/reachdog/langchain-reachdog) (`pip install langchain-reachdog==0.1.0`) |
| n8n workflow templates | [github.com/reachdog/reachdog-n8n-templates](https://github.com/reachdog/reachdog-n8n-templates) |
| Recorded requests and responses, no key needed | [Hugging Face demo](https://huggingface.co/spaces/ReachDog/product-classification-api-demo) |

## Using an AI coding assistant

These docs are published as plain text for AI tools. Point your assistant at [platform.reach.dog/llms.txt](https://platform.reach.dog/llms.txt), or at any page with `.md` added, such as [platform.reach.dog/docs/api-reference.md](https://platform.reach.dog/docs/api-reference.md), and ask it to write the integration for your stack.

## Before you send

Use `https://api.reach.dog` from your server. Keep your API key in an environment variable. The console's sign-in cookie is not an API key.

## Getting started: which parameter should I try first?

For a first experiment, try `product_type` in the Playground's title-match request. It returns what the product is as a short noun phrase, so it is an easy output to understand and compare with your input. Enter a clear English product title such as "Red wool scarf", select only `product_type`, review the displayed cost and access requirements, then send when ready. A request body is `{"title":"Red wool scarf","parameters":["product_type"]}` for `POST /v1/title-matches`.

Next, add `attributes` to explore product details, or `categories` for classification. Start with one output so you can see what it contributes before choosing more. Asking the help assistant is free of wallet charges; sending a playground API request may spend credits. Help cannot enable access or send a request for you.

For market research, start with a product-type subject and `market_coverage` to explore the tracked population. For content generation, first obtain a completed title result, then use that saved result as the source for `content_brief` with a supported channel such as `blog`. The best starting output depends on whether you want product facts, market research, or content; the title-match example is a simple starting point when you have not chosen a task yet.

## Authentication and retries

Send `Authorization: Bearer <REACHDOG_API_KEY>` on API requests. Every creation request also needs an `Idempotency-Key` of 1--200 characters. Set `REACHDOG_REQUEST_ID` to a unique value for new work and retain it with the request. Retry the same body with the same key after a timeout or uncertain outcome. A new key starts new work and may incur a new charge. Reusing a key with different input returns 409.

```bash
curl https://api.reach.dog/v1/title-matches \
  -H "Authorization: Bearer $REACHDOG_API_KEY" \
  -H "Idempotency-Key: $REACHDOG_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"title":"Red wool scarf","parameters":["brand","attributes"]}'
```

## Interactive endpoints

| Endpoint | Scope | Request |
|---|---|---|
| `POST /v1/title-matches` | `match` | `title`, `parameters`; optional `client_product_id`, `locale`, `market` and other documented API schema fields |
| `POST /v1/market-research` | `research` | `subject`, `parameters`; optional `market`, `locale` |
| `POST /v1/content-generations` | `content` | `source`, `parameters`, `channels`; optional `locale` |
| `GET /v1/usage` | `read` | No body |

Responses contain exactly the requested parameter names. See [Parameter reference](parameter-reference.md) for their shapes and examples. `X-Result-ID` and `Location` identify the saved result; retain them for later research/content requests. `X-Request-ID` identifies a request for support. Applicable responses may include `X-Parameter-Status` to explain missing or partial data.

### Title matches

The title must contain 1--1,000 characters and cannot be blank. Select at least one supported parameter. `localized_terms` requires `locale`; omit locale otherwise. A locale is at most 35 characters, such as `en-US`. `keyword_product_matches` requires `client_product_id` (1--200 characters). `market`, when supported by the selected operation, is 2--20 characters. Title `keywords` and `channel` inputs are not supported by this console's API contract. The playground also accepts description (up to 10,000 characters), up to 40 named attributes (names up to 80 characters, nonblank values up to 1,000), and language (2 to 20 characters). English (`en`) is the only language currently processed by the API. History preserves other language values for inspection, but Send stays disabled for those values. Use English product text before choosing `en`. Changing the language field does not translate the text. Description and attributes can add product facts and guide shopping context. The title still determines product identity and search; supplied details are not independently verified. Input attributes are separate from the requested `attributes` output.

### Market research

Subjects may be a `product_type`, `category`, or `brand` with `value`; a `dimension` with `dimension` and `value`; an owned `title_result` with `id`; or an owned `catalog_group` with `grouping_id` and `group_id`. Send only the fields for that type. Dimensions are `season`, `demographic`, `occasion`, and `use_case`.

```json
{"subject":{"type":"product_type","value":"camping tents"},"parameters":["market_coverage","brand_presence"]}
```

`geographic_demand` requires an uppercase two-letter country code in `market` and English locale (`en` or omitted). Request it separately from parameters based on global market data. Market observations describe tracked populations, not sales or total market share.

### Content generation

Content requires an owned completed title result or catalog group. Group sources are bounded to 50 products. Other subject types are not accepted for content generation.

```json
{"source":{"subject":{"type":"title_result","id":"YOUR_SAVED_RESULT_ID"},"objective":"Introduce the product"},"parameters":["blog_topics","content_brief"],"channels":["blog"]}
```

Optional `objective` and `brand_voice` are each at most 1,000 characters. Select 1--10 channels: `blog`, `sem`, `email`, `product`, `instagram`, `facebook`, `x`, `pinterest`, `tiktok`, `youtube`.

The limit is 16 distinct output-channel pairs. The three topic parameters share one output; each other content parameter maps to a separate output. For example, `ad_topics`, `blog_topics`, and `content_brief` across eight channels use two outputs × eight channels = 16 pairs. `ad_topics` requires `sem`, `blog_topics` requires `blog`, and `video_topics` requires `youtube` or `tiktok`.

## Usage, pricing, and failures

Usage reports API allowances separately from the token wallet. Read current pricing and balance from the service; displayed examples are not price guarantees. Legacy beta accounts may be unbilled. Completed same-key replay and saved reads do not generate or charge again. Canceling a browser request does not guarantee that server work stopped.

| Status | Action |
|---|---|
| 401 | Check the API key or renew console sign-in, depending on where the request was sent. |
| 402 | Check wallet balance. |
| 403 | Check ownership, scope, or wallet eligibility. |
| 409 | Inspect the error code: work may still be running, or the idempotency key may conflict. |
| 422 | Correct the request or unsupported selection. |
| 429 | Respect the reported allowance/concurrency limit and retry delay. |
| 503 | Preserve the request key while resolving an uncertain outcome or dependency outage. |

## Console availability

This console build supports Accounts session validation, request preparation, browser-local saved requests, and documentation. Key management, live playground execution, and usage require the deployed Accounts integration; the API keys page provides explicit playground access setup and replacement. The Wallet page and buying tokens depend on the capabilities returned for your current session and service configuration. Use the displayed wallet status and purchase options to check availability; documentation cannot establish an individual account's access. Reading an existing owned catalog group does not imply permission to create new paid groupings.

## Help and guidance

Open Help in the console header to search these API docs and find guides for the current page. The question-mark controls beside playground parameters explain their meaning and return types; they work with a mouse, keyboard or touch.

Signed-in users can ask general API questions in their own words, then press Enter or choose Ask assistant to get an explanation based on the API documentation. For example, ask "What is the first parameter I should try?". The related documentation list is keyword search, separate from the assistant answer. Answers include source links. If the selected documentation does not cover the question, the assistant says so. It cannot inspect your balance, keys, catalog or request history, or perform actions for you. Do not include secrets or private data in questions. Questions and answers are not saved as a conversation by this service.

Help does not charge wallet credits or require enabling the playground. Questions are limited to 500 characters. If help is busy or unavailable, use documentation search or wait before asking again. Browser cancellation stops waiting for the answer but may not stop an already-running model call.
# Catalog workflow

For `POST /v1/batches` with `workflow: catalog_local_v1`, quote acceptance,
polling, paginated results, cancellation and payment recovery, see the
[catalog workflow guide](/docs/catalog-workflow). It covers all ten selectable
outputs, limits, retention and wallet billing. See [API key scopes](/docs/key-scopes)
for the scopes each workflow needs.
