# 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. Minimum $20.
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.20 | ~1.5 min | Verdict, 5 scores, evidence for each score |
| `full` | $0.50 | 2–3 min | Everything in light, deeper web research, competitor details, risk research, pivot ideas when the verdict is PIVOT |
| `domains` | $0.20 | ~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}`. 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

```json
{
  "call_id": "…", "status": "COMPLETED", "tier": "light", "cost_usd": 0.20,
  "result": {
    "verdict": {"type": "CONDITIONAL_GO", "conviction": 55, "summary": "…",
                "conditions_for_success": ["…"], "next_steps": ["…"], "kill_criteria": [{"trigger": "…", "action": "…", "deadline": "…"}]},
    "scores": {"demand": 74, "competition": 42, "problem_fit": 72, "economics": 58, "risk": 62, "overall": 63},
    "demand": {"…": "market size, search volume, sources"},
    "competitors": {"…": "competitors, gaps, sources"},
    "problem_fit": {"…": "pain severity, willingness to pay, pain_type: painkiller or vitamin"},
    "unit_economics": {"…": "LTV, CAC, churn, payback"},
    "risks": {"…": "failure reasons with severity and mitigation"},
    "pivot": null
  }
}
```

Scores are 0–100. For `competition`, higher means more opportunity and less threat. For `risk`, higher means more risk.

## Find a domain name

`POST /agent/v1/domains` returns up to 10 free domain names for a product. It costs $0.20 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.20. 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. |
| `create_topup` | Argument `amount_usd`. Returns `checkout_url` for a human to pay. |

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.