Skip to main content
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

FieldTypeRequiredDefaultDescription
ideastringYesThe app idea in plain language (8–600 characters).
countrystringNousISO 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"
  }'

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

FieldTypeDescription
statusstringqueued | processing | completed | failed
resultobjectThe full validation result (see below); null until done.
errorstringSet only if the whole job failed.

Result Fields

FieldTypeDescription
planobjectRefined idea summary, category, search queries, and seed keywords.
competitorsarrayMatching live apps, with revenue/download estimates where available.
keywordsarraySeed keywords with volumeScore (0–100) and difficulty (0–100).
painPointsarrayRecurring complaints mined from competitor reviews (frequency: low/med/high).
verdictScorenumber0–100 — how validated the idea is by the evidence.
verdictstringbuild | validate | pivot | avoid.
marketSummarystring2–3 sentences on whether there’s a real market.
demandSignalstringOne line on search demand.
competitionLevelstringOne line on how crowded / monetized the space is.
differentiationAnglestringThe sharpest wedge, grounded in pain points.
risksstring[]Up to four concrete risks.
marketingobjectSuggested name, subtitle, keywords, positioning, audience, go-to-market.

MCP Tools

ToolDescription
validate_ideaStart a validation run for an app idea; returns a jobId.
get_idea_validation_jobPoll status and the full result for a run.

Errors

StatusCodeWhen
400INVALID_IDEAidea missing or shorter than 8 characters
400IDEA_TOO_LONGidea longer than 600 characters
401UNAUTHORIZEDMissing or invalid credentials
403FORBIDDENPolling a job that belongs to another account
404JOB_NOT_FOUNDUnknown jobId