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

# Idea Validation

> Validate a plain-language app idea against the live App Store — real competitors, keyword demand, review pain points, an AI verdict, and a go-to-market starter pack

```
POST /v1/validate-idea
GET  /v1/validate-idea/jobs/:jobId
```

Turn a one-line app idea into **real App Store evidence**. Instead of guessing, this endpoint searches the live store for direct competitors (with revenue and download estimates), measures keyword demand vs ranking difficulty, mines recurring complaints from competitor reviews, then synthesizes a **verdict** (0–100) and a **go-to-market / ASO starter pack** with an LLM.

The work runs asynchronously on a background job, so `POST /v1/validate-idea` returns a `jobId` immediately (HTTP `202`). Poll `GET /v1/validate-idea/jobs/:jobId` for the full result.

<Note>
  Every number in the result is grounded in live App Store data — competitor revenue, keyword difficulty, and verbatim user complaints — not the model's prior. The LLM is instructed to reason from the gathered evidence.
</Note>

***

## Create a run

```
POST /v1/validate-idea
```

### Request Body

| Field     | Type   | Required | Default | Description                                           |
| --------- | ------ | -------- | ------- | ----------------------------------------------------- |
| `idea`    | string | Yes      | —       | The app idea in plain language (8–600 characters).    |
| `country` | string | No       | `us`    | ISO 3166-1 alpha-2 storefront to research, e.g. `gb`. |

<Tip>
  Cost is metered at a flat **12 credits per run** (one idea-parse call, several App Store lookups, and two synthesis LLM calls). The poll endpoint is free.
</Tip>

### Code Examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/validate-idea" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "idea": "An AI-powered budgeting app that auto-categorizes spending and warns you before you overspend",
      "country": "us"
    }'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // 1. Start the run
  const start = await fetch("https://api.appeeky.com/v1/validate-idea", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      idea: "An AI-powered budgeting app that warns you before you overspend",
      country: "us",
    }),
  });
  const { data } = await start.json();
  const jobId = data.jobId;

  // 2. Poll for the result
  async function poll() {
    const res = await fetch(
      `https://api.appeeky.com/v1/validate-idea/jobs/${jobId}`,
      { headers: { "X-API-Key": "YOUR_API_KEY" } }
    );
    const { data } = await res.json();
    if (data.status === "completed" || data.status === "failed") return data;
    await new Promise((r) => setTimeout(r, 4000));
    return poll();
  }
  console.log(await poll());
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import time, requests

  headers = {"X-API-Key": "YOUR_API_KEY"}

  start = requests.post(
      "https://api.appeeky.com/v1/validate-idea",
      headers=headers,
      json={
          "idea": "An AI-powered budgeting app that warns you before you overspend",
          "country": "us",
      },
  )
  job_id = start.json()["data"]["jobId"]

  while True:
      res = requests.get(
          f"https://api.appeeky.com/v1/validate-idea/jobs/{job_id}",
          headers=headers,
      ).json()["data"]
      if res["status"] in ("completed", "failed"):
          break
      time.sleep(4)

  print(res)
  ```
</CodeGroup>

### Response (`202 Accepted`)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "jobId": "f3c1a2b4-...",
    "triggerRunId": "run_...",
    "status": "queued",
    "idea": "An AI-powered budgeting app that warns you before you overspend",
    "country": "us"
  }
}
```

***

## Poll for the result

```
GET /v1/validate-idea/jobs/:jobId
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "jobId": "f3c1a2b4-...",
    "status": "completed",
    "idea": "An AI-powered budgeting app that warns you before you overspend",
    "country": "us",
    "result": {
      "plan": {
        "summary": "An AI budgeting app that proactively prevents overspending.",
        "category": "Finance",
        "searchQueries": ["budget app", "spending tracker", "money manager"],
        "seedKeywords": ["budget", "budgeting app", "expense tracker", "spending", "savings"]
      },
      "competitors": [
        {
          "appId": "1602117440",
          "title": "Example Budget",
          "developer": "Example Inc.",
          "icon": "https://...",
          "rating": 4.7,
          "reviewsCount": 48211,
          "isFree": true,
          "estimatedDownloads": 1200000,
          "estimatedRevenue": 240000,
          "humanizedDownloads": "~1.2M",
          "humanizedRevenue": "~$240k"
        }
      ],
      "keywords": [
        { "keyword": "budget", "volumeScore": 78, "difficulty": 64 },
        { "keyword": "expense tracker", "volumeScore": 55, "difficulty": 41 }
      ],
      "painPoints": [
        {
          "theme": "Sync reliability",
          "detail": "Users report bank sync breaking and transactions not importing.",
          "quote": "It keeps disconnecting from my bank every week",
          "frequency": "high"
        }
      ],
      "verdictScore": 72,
      "verdict": "validate",
      "marketSummary": "A large, actively monetizing market with several apps above $100k/mo, but dominated by sync reliability complaints you can exploit.",
      "demandSignal": "High search demand on core terms (volume 78) with mid difficulty.",
      "competitionLevel": "Crowded but monetizing — leaders earn six figures monthly.",
      "differentiationAngle": "Win on rock-solid bank sync plus proactive overspend alerts.",
      "risks": ["Bank-sync infrastructure cost", "Incumbent brand trust"],
      "marketing": {
        "suggestedName": "Spendwise: Budget Guard",
        "suggestedSubtitle": "Stop overspending today",
        "suggestedKeywords": "budget,spending,expense,money,savings,finance,tracker,bills",
        "positioning": "The budgeting app that warns you before you overspend, not after.",
        "targetAudience": "Younger professionals who overspend and want guardrails.",
        "goToMarket": ["Launch on Product Hunt", "Target 'budget app' ASA keywords", "Partner with finance creators"]
      }
    },
    "error": null,
    "createdAt": "2026-06-21T09:00:00.000Z",
    "updatedAt": "2026-06-21T09:00:48.000Z"
  }
}
```

### Job Fields

| Field    | Type   | Description                                                |
| -------- | ------ | ---------------------------------------------------------- |
| `status` | string | `queued` \| `processing` \| `completed` \| `failed`        |
| `result` | object | The full validation result (see below); `null` until done. |
| `error`  | string | Set only if the whole job failed.                          |

### Result Fields

| Field                  | Type      | Description                                                                     |
| ---------------------- | --------- | ------------------------------------------------------------------------------- |
| `plan`                 | object    | Refined idea summary, category, search queries, and seed keywords.              |
| `competitors`          | array     | Matching live apps, with revenue/download estimates where available.            |
| `keywords`             | array     | Seed keywords with `volumeScore` (0–100) and `difficulty` (0–100).              |
| `painPoints`           | array     | Recurring complaints mined from competitor reviews (`frequency`: low/med/high). |
| `verdictScore`         | number    | 0–100 — how validated the idea is by the evidence.                              |
| `verdict`              | string    | `build` \| `validate` \| `pivot` \| `avoid`.                                    |
| `marketSummary`        | string    | 2–3 sentences on whether there's a real market.                                 |
| `demandSignal`         | string    | One line on search demand.                                                      |
| `competitionLevel`     | string    | One line on how crowded / monetized the space is.                               |
| `differentiationAngle` | string    | The sharpest wedge, grounded in pain points.                                    |
| `risks`                | string\[] | Up to four concrete risks.                                                      |
| `marketing`            | object    | Suggested name, subtitle, keywords, positioning, audience, go-to-market.        |

***

## MCP Tools

| Tool                      | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `validate_idea`           | Start a validation run for an app idea; returns a `jobId`. |
| `get_idea_validation_job` | Poll status and the full result for a run.                 |

***

## Errors

| Status | Code            | When                                          |
| ------ | --------------- | --------------------------------------------- |
| 400    | INVALID\_IDEA   | `idea` missing or shorter than 8 characters   |
| 400    | IDEA\_TOO\_LONG | `idea` longer than 600 characters             |
| 401    | UNAUTHORIZED    | Missing or invalid credentials                |
| 403    | FORBIDDEN       | Polling a job that belongs to another account |
| 404    | JOB\_NOT\_FOUND | Unknown `jobId`                               |