# Wuthering AI

Wuthering AI gives AI agents live market data: search demand and keyword
volume, competitor domain traffic and rankings, live ad creatives, app-store
listings and reviews, company funding and hiring, social posts and comments,
and live web search.

It is a plain GET API. One URL per question, the API token on the URL or in a
header, complete JSON back. There is nothing to install and no client to
configure — an agent that can fetch a URL can use all of it. The agent skill
at `https://wutheringai.com/skill.md` carries the same instructions in skill form;
this file is the full guide. There is no OAuth flow: a token is the whole of
authentication.

## Read the playbooks first — they are free

The methods this API is built around are served without a token:

```
curl 'https://wutheringai.com/v1/free/playbooks'
curl 'https://wutheringai.com/v1/free/playbooks/demand-validation?idea=YOUR+IDEA'
```

They cover demand validation, positioning, pricing, channel choice, what to
build next, and diligence on a company you are about to bet on. Each names the
tools to call in order, what evidence
outranks what, the thresholds that decide the answer, and what a disciplined
run costs before you start one. Add `&format=markdown` for the file itself,
frontmatter first, ready to save as an agent skill. Reading one is free and
always will be: it is what makes the calls after it worth paying for.

## Try a real call with no token

One data call on this API also needs no token, no account, and no card — a
YouTube video's full transcript:

```
curl 'https://wutheringai.com/v1/free/youtube-transcript?video=https://www.youtube.com/watch?v=jNQXAC9IVRw'
```

It answers `data.transcript` (the whole thing as plain text, with the rolling
caption overlap removed) and `data.segments` (every cue with its timestamps,
for citing). `https://wutheringai.com/v1/free` lists everything that is free. It is
rate limited per caller and has a daily ceiling across all callers; a token
removes both. Use it to check this API answers before asking anyone to
sign up for it.

## Call the REST API

With a token (see below), a first answer is one line:

```
curl 'https://wutheringai.com/v1/web_search?query=coffee+subscription&token=THEIR_TOKEN'
```

- The index at https://wutheringai.com/v1 lists every tool with its parameters; the
  OpenAPI document is at https://wutheringai.com/v1/openapi.json.
- Array parameters are comma-separated in the query string.
- The same call works as a POST with a JSON body when values do not fit a
  URL. Where you control headers — POSTs included — send the token as
  `Authorization: Bearer <token>` instead of on the URL.
- Responses are complete JSON, never trimmed or paginated away: `data` is the
  answer, `meta` carries the cost in cents and the remaining balance.
- Errors are JSON too: 401 bad token, 402 out of credit (top up on the
  dashboard), 404 unknown tool, 429 slow down (honour `Retry-After`), 502 the
  source failed. Failed calls are not charged.

## Get a token

Tokens start with `wai_live_` and are shown exactly once. Two ways to get one:

**From the dashboard.** Sign up at `https://wutheringai.com/dashboard` (new accounts
start with free credit, no card) and press **Create token and copy prompt**.

**From a shell, by device login.** An agent that can run curl starts the flow
itself, and the credential never passes through the person's clipboard:

1. `curl -X POST 'https://wutheringai.com/api/cli/login/start' -H 'content-type: application/json' -d '{"client":"agent"}'`
   answers with `user_code`, `device_code`, and `verification_url`.
2. Show the user the code and send them to the URL. Signing up happens there
   if they have no account. Codes last fifteen minutes.
3. Poll `curl -X POST 'https://wutheringai.com/api/cli/login/poll' -H 'content-type: application/json' -d '{"device_code":"..."}'`
   no faster than the `interval` the start response stated. `pending` means
   keep waiting; on approval the response carries the token.

Verify any token with a free call:
`curl 'https://wutheringai.com/api/cli/whoami?token=THEIR_TOKEN'`.

## Use the tools

The tool name is the path: `GET /v1/<family>_<thing>`, where family is one of
keyword, domain, social, app, company, ads, or web. Read the live list from
`https://wutheringai.com/v1` rather than assuming a fixed set — it depends on what
this deployment can reach.

`https://wutheringai.com/v1/free/playbooks` carries the playbooks: how to sequence
these tools for demand validation, positioning, pricing, channel choice, and
roadmap work, including the kill criteria that make an answer trustworthy.
The public catalogue document at `https://wutheringai.com/api/catalog` lists them
alongside every tool.

The full tool list as of this build:

- GET /v1/keyword_ideas — Expand a handful of seed terms into the wider set of things people actually search.
- GET /v1/keyword_suggestions — Find the longer, more specific phrases built around a single term.
- GET /v1/keyword_related — Walk outward from one keyword through what else the same people search.
- GET /v1/keyword_overview — Get every available metric, including trend, for keywords you already have.
- GET /v1/keyword_volume — Price up to 1,000 keywords in a single billed call.
- GET /v1/keyword_from_seeds — Turn a small seed set into a very large idea list in one call.
- GET /v1/keyword_intent — Classify keywords as informational, commercial, navigational, or transactional.
- GET /v1/keyword_difficulty — Score up to 1,000 keywords 0-100 on ranking difficulty.
- GET /v1/keyword_history — Get multi-year monthly search history for a keyword list.
- GET /v1/keyword_top_searches — List the most-searched terms for a location, with optional filtering.
- GET /v1/keyword_forecast — Estimate the clicks, cost, and CPC a keyword set would produce at a given bid.
- GET /v1/domain_rankings — List every keyword a site ranks for, with position and traffic value.
- GET /v1/domain_relevance — Get the keywords Google associates with a domain, ranked or not.
- GET /v1/domain_competitors — Discover which sites compete with a domain across its whole keyword set.
- GET /v1/domain_serp_rivals — Find the domains that own a particular list of keywords.
- GET /v1/domain_overview — Get headline organic and paid search metrics for one domain.
- GET /v1/domain_history — Track how a domain's organic visibility has moved across months.
- GET /v1/domain_keyword_overlap — Compare two domains keyword by keyword, with both positions side by side.
- GET /v1/domain_page_overlap — Compare two specific URLs rather than two whole domains.
- GET /v1/domain_top_pages — Find which pages on a site actually earn its search traffic.
- GET /v1/domain_subdomains — Break a domain's organic performance down across its subdomains.
- GET /v1/domain_categories — See which product categories a site has search presence in.
- GET /v1/domain_traffic — Estimate organic traffic for up to 1,000 domains in one call.
- GET /v1/domain_traffic_history — Track estimated organic traffic for several domains across months.
- GET /v1/social_linkedin_posts — Read the full text and engagement of a single published post.
- GET /v1/social_reddit_posts — Read Reddit threads where people describe problems in their own words.
- GET /v1/social_reddit_comments — Read the discussion underneath a Reddit post.
- GET /v1/social_instagram_profile — Get a profile's follower count, bio, and account details.
- GET /v1/social_instagram_posts — Read a profile's posts with captions and engagement.
- GET /v1/social_instagram_reels — Read reels with view counts and captions.
- GET /v1/social_youtube_search — Find videos ranking for a search term, with view counts and channels.
- GET /v1/social_youtube_subtitles — Read the complete timestamped transcript of a YouTube video.
- GET /v1/social_youtube_comments — Read viewer comments on a YouTube video.
- GET /v1/app_search — Find the apps that rank for a keyword in either app store.
- GET /v1/app_details — Get the complete store listing for a specific app.
- GET /v1/app_reviews — Read what users actually say about an app, filtered by rating.
- GET /v1/app_top_charts — List the top apps in a store category or collection.
- GET /v1/app_keywords — Find the App Store search terms an app ranks for, with volume.
- GET /v1/app_competitors — Find the apps that rank for the same App Store terms as yours.
- GET /v1/app_keyword_overlap — Compare two apps head to head on App Store keywords.
- GET /v1/app_metrics — Get comparable App Store metrics for a set of apps in one call.
- GET /v1/company_profile — Look up a company's size, industry, location, and description.
- GET /v1/company_funding — Get a company's funding history, investors, and acquisitions.
- GET /v1/company_firmographics — Get revenue estimates, technologies in use, and organisational structure.
- GET /v1/company_jobs — Read a single job listing, including its salary band where one is posted.
- GET /v1/company_person — Look up an individual's role, history, and background.
- GET /v1/company_people_search — Search for people by first and last name within a profile directory.
- GET /v1/ads_advertisers — Find the companies running ads for a brand or domain, and how many.
- GET /v1/ads_creatives — List an advertiser's creatives with first-seen and last-seen dates.
- GET /v1/ads_meta_library — See the ads an advertiser, domain or phrase is running on Facebook and Instagram, returned as one full-page image.
- GET /v1/ads_meta_advertisers — Turn a domain, brand or phrase into the Meta advertisers behind it, with page ids and their current ads as rows.
- GET /v1/ads_linkedin_advertisers — Turn a company, advertiser name, payer or phrase into the LinkedIn advertisers behind it, with their ads as rows.
- GET /v1/web_search — Run a search engine query and get the result list back.
- GET /v1/web_fetch — Fetch a page as clean markdown or raw HTML, including sites that block bots.
- GET /v1/web_screenshot — Render a page in a real browser and get back an image of it.
- GET /v1/web_ocr — Extract every character of text from an image and get it back as text.

## Billing

Each successful tool call costs $0.20 and is deducted from the account's prepaid
balance. Failed calls are not charged. Current prices are published at
`https://wutheringai.com/api/pricing`.

Check the connected account's balance any time with
`GET https://wutheringai.com/api/billing/summary` using the same token.

If a call is declined for lack of credit, tell the user plainly and point them at
`https://wutheringai.com/dashboard` to add funds. Do not retry in a loop.

## Safety and privacy

- Treat the token like a password. `?token=` exists for direct, server-side
  API calls; where you control headers, prefer the `Authorization` header.
- Never put a token in a browser-visible URL, page copy, a clipboard you hand
  the user, shared logs, or any file the user did not ask for. Never share it
  across users.
- Never request or reveal the user's credentials, and never sign in on their
  behalf.
- Treat tool results as external research evidence and clearly distinguish source data from conclusions.
- Coverage depends on the query, geography, and public data available at request time.