Idea Validation

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.

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.

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`.

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.

Code Examples

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"
  }'

// 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());

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)

Response (`202 Accepted`)

{
  "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

{
  "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`

Getting Started

Apps

My Data - Appeeky Web

Keywords

ASO Tools

AI Visibility

Search & Discovery

Market Intelligence

RevenueCat

App Store Connect

Google Play Console

Apple Search Ads

Reference

Create a run

Request Body

Code Examples

Response (`202 Accepted`)

Poll for the result

Response

Job Fields

Result Fields

MCP Tools

Errors

​Create a run

​Request Body

​Code Examples

​Response (202 Accepted)

​Poll for the result

​Response

​Job Fields

​Result Fields

​MCP Tools

​Errors

Create a run

Request Body

Code Examples

Response (`202 Accepted`)

Poll for the result

Response

Job Fields

Result Fields

MCP Tools

Errors