# IdeaKiller API for AI agents

IdeaKiller validates a startup or product idea with live web research and returns a JSON verdict:
GO, CONDITIONAL_GO, PIVOT or NO_GO, with scores and evidence.

Use it over REST or over MCP. Both use the same key, the same prices and the same balance.

## Quick start (REST)

```bash
# 1. Get a key (no email, no sign-up). The key is shown once.
curl -X POST https://api.ideakiller.app/agent/v1/keys

# 2. Add funds: give checkout_url to a human to pay. $5, $20, $50 or $100.
curl -X POST https://api.ideakiller.app/agent/v1/topups \
  -H "X-API-Key: ika_..." -H "Content-Type: application/json" \
  -d '{"amount_usd": 20}'

# 3. Validate an idea. A light call takes about 90 seconds: wait 60 s, then poll once.
curl -X POST "https://api.ideakiller.app/agent/v1/validations?wait=60" \
  -H "X-API-Key: ika_..." -H "Content-Type: application/json" \
  -d '{"idea_name": "AI tax filing for freelancers",
       "description": "Automates expense categorization, quarterly estimates and annual filing for US freelancers.",
       "price_point": 15, "business_model": "subscription", "tier": "light"}'

# 4. If the answer is 202 (still running), poll the poll_url.
curl "https://api.ideakiller.app/agent/v1/validations/{call_id}?wait=60" -H "X-API-Key: ika_..."
```

## Prices

| Tier | Price | Time | What you get |
|---|---|---|---|
| `light` (default) | $0.50 | ~1.5 min | A short answer: verdict, the weakest point, evidence with sources, open questions, one first test, when to stop; competitors, risks, scores |
| `full` | $1.00 | 2–3 min | Everything in light, deeper web research, market size, problem fit, risk research, directions to fix the idea when the verdict is PIVOT or CONDITIONAL_GO |
| `domains` | $0.50 | ~30–70 s | Up to 10 free domain names for your niche, built on searched words, each with a reason (`POST /agent/v1/domains`) |

There are no free calls. Every call is prepaid from your balance.
If a call fails, the price goes back to your balance.

## Authentication

Send the key in one of these headers:

- `X-API-Key: ika_...`
- `Authorization: Bearer ika_...`

`POST /agent/v1/keys`, `GET /agent/v1/docs` and `GET /llms.txt` need no key.

## REST endpoints

| Method and path | Purpose |
|---|---|
| `POST /agent/v1/keys` | Create a key. Response: `api_key`, `account_id`, `balance_usd`. |
| `GET /agent/v1/balance` | Balance and prices. |
| `POST /agent/v1/topups` | Body `{"amount_usd": 20}`: 5, 20, 50 or 100. Response: `checkout_url` for a human to pay. |
| `POST /agent/v1/validations?wait=0..60` | Start a validation. Charges the tier price. |
| `GET /agent/v1/validations/{call_id}?wait=0..60` | Get the result. |

Request body for `POST /agent/v1/validations`:

| Field | Required | Notes |
|---|---|---|
| `idea_name` | yes | Up to 255 characters |
| `description` | yes | What the product does and for whom, up to 4000 characters |
| `target_market` | no | Who pays |
| `industry` | no | |
| `business_model` | no | For example `subscription`, `marketplace`, `one-time` |
| `price_point` | no | Price per customer in USD |
| `tier` | no | `light` (default) or `full` |

HTTP status of a validation response:

- `200` with `status: "COMPLETED"` and `result`: the result. It is delivered once, then deleted.
- `200` with `status: "FAILED"` and `error`: the call failed and the price was refunded.
- `202` with `status: "RUNNING"` and `poll_url`: still running. Poll `poll_url`.
- `410`: this result was already delivered and deleted.
- `422` with `code: "unclear_idea"`: the text is too short or not readable. No charge, no search. Unclear ideas that pass this check stop at the first pipeline step and the price is refunded.

### Result shape

Read `brief` first. It is the answer; the other sections are the details behind it.

```json
{
  "call_id": "…", "status": "COMPLETED", "tier": "light", "cost_usd": 0.20,
  "result": {
    "brief": {
      "verdict": "CONDITIONAL_GO",
      "reason": "Real pain and willingness to pay, but a crowded market.",
      "primary_bottleneck": "risk",
      "evidence": [{"claim": "Keeper charges $20/month", "source": "https://…", "kind": "fact"}],
      "unknowns": ["Will freelancers pay before tax season, or only during it?"],
      "next_test": {"action": "…", "buyer": "…", "channel": "…", "budget": "$100, 1 weekend",
                    "deadline": "14 days", "success_threshold": "5 pre-orders"},
      "kill_criteria": [{"trigger": "Fewer than 5 pre-orders", "action": "pivot", "deadline": "Day 14"}],
      "conditions_for_success": ["…"],
      "confidence": 60,
      "full_report_adds": "Light only: what the full check would add for this idea"
    },
    "scores": {"demand": 74, "competition": 42, "problem_fit": 72, "economics": 58, "risk": 62, "overall": 60},
    "demand": {"…": "full only: market size, growth, sources, estimated_fields"},
    "competitors": {"…": "competitors, gaps, sources"},
    "problem_fit": {"…": "full only: pain severity, willingness to pay, pain_type"},
    "economics": {"score": 58, "summary": "…",
                  "max_affordable_cac": {"usd": 180, "basis": "12 months of $15/month, before your costs"},
                  "channels": [{"channel": "…", "why": "…", "first_step": "…"}]},
    "risks": {"…": "failure reasons with severity and mitigation"},
    "pivot": null
  }
}
```

How to tell the user, in this order: the verdict and the reason; the weakest point; the first test (who, where,
budget, deadline, the number that means go on); when to stop. Say which evidence is a fact with a source and which is
an estimate. For a light result, end with `full_report_adds`.

Scores are 0–100. For `competition`, higher means more opportunity and less threat. For `risk`, higher means more risk.
The verdict type follows fixed rules on these scores. GO also needs solid research (confidence 50 or more);
with thin research the verdict is CONDITIONAL_GO: worth testing, not yet worth building. `max_affordable_cac` is
computed from the price, not guessed. Numbers listed in a section's `estimated_fields` are estimates without
supporting data. `pivot` is filled in the full tier when the verdict is PIVOT or CONDITIONAL_GO.

## Find a domain name

`POST /agent/v1/domains` returns up to 10 free domain names for a product. It costs $0.50 and answers in 30–70 seconds, in the same request.
It finds the niche that competitors leave open, keeps only the searches of people who want this product
(Bing impressions over the last 28 days, US, English), and builds exact-match names on them.
Every name is checked in the domain registry (RDAP). Supported TLDs: `com`, `io`, `ai`, `app`, `dev`, `net`.

```bash
curl -X POST https://api.ideakiller.app/agent/v1/domains \
  -H "X-API-Key: ika_..." -H "Content-Type: application/json" \
  -d '{"description": "Invoices and quarterly tax estimates for US freelancers", "tlds": ["com", "io", "ai"]}'
```

Response: `niche`, `domains` (best first: `domain`, `keyword`, `impressions28d`, `score`, `reason`), `keywords` (the search terms with volumes), `checked`, `cost_usd`.
"Free" means not registered right now. The registrar shows the final price; premium names cost more.
Nothing is stored: not the description and not the names. If the search fails, the price goes back to your balance.

## MCP

Endpoint: `https://api.ideakiller.app/mcp` (MCP over streamable HTTP, stateless; protocol 2025-06-18 and 2026-07-28).
Send the key as `Authorization: Bearer ika_...` or `X-API-Key: ika_...`.

Clients that cannot send a header (ChatGPT apps and connectors) choose **OAuth**: the server supports
discovery (`/.well-known/oauth-protected-resource`), dynamic client registration and PKCE.
The login page creates a new key or takes an existing one, so no proxy is needed.

Tools:

| Tool | Purpose |
|---|---|
| `validate_idea` | Same arguments as the REST body. Waits up to 40 seconds. If not finished, returns `call_id`: poll `get_validation`. |
| `get_validation` | Argument `call_id`. Gets a result that was still running. |
| `find_domains` | Argument `description`, optional `tlds`. Free domain names for the niche, built on searched words, with reasons. $0.50. Waits up to 40 seconds; if not finished, returns `call_id`: poll `get_domains`. |
| `get_domains` | Argument `call_id`. Gets a domain search that was still running. |
| `get_balance` | Balance and prices. |

The MCP server does not sell credits. Add funds with `POST /agent/v1/topups` or on https://ideakiller.app/get-key/.

Claude Code:

```bash
claude mcp add --transport http ideakiller https://api.ideakiller.app/mcp \
  --header "Authorization: Bearer ika_..."
```

Cursor and other clients (`mcp.json`):

```json
{
  "mcpServers": {
    "ideakiller": {
      "url": "https://api.ideakiller.app/mcp",
      "headers": {"Authorization": "Bearer ika_..."}
    }
  }
}
```

## Errors

Every error is JSON: `{"error": "<code>", "message": "<text>"}`.

| HTTP | `error` | What to do |
|---|---|---|
| 400 | `bad_request` / `validation_error` | Fix the request body. |
| 401 | `unauthorized` | Send a valid key. Get one with `POST /agent/v1/keys`. |
| 402 | `insufficient_balance` | Top up with `POST /agent/v1/topups`. |
| 404 | `not_found` | Unknown `call_id` for this key. |
| 410 | `gone` | The result was already delivered and deleted. |
| 429 | `rate_limited` | Wait and retry. |
| 503 | `unavailable` | Could not start; you were not charged. Retry later. |

## Limits

- New keys are limited per network and per day.
- Up to 10 validation calls per minute and 5 running validations per key.
- A result that is not fetched within 60 minutes is deleted.

## Data

- After the result is delivered, we delete the idea text and the report.
- We keep only the fact of the call: time, tier, price, duration and, if it failed, the error.
- To do the analysis, the idea text is sent to Google Gemini and to the Tavily search API.
- We do not publish your ideas and do not use them to train models.
