Reference

API Docs

IdeaRoast exposes a small set of HTTP endpoints for integrating roast functionality into your own agents or tools. All endpoints are unauthenticated unless noted. The base URL is https://www.idearoast.dev.

POST/api/roast/free

Free Roast

Runs a quick single-agent roast at no cost. Rate limited to one request per IP per day. No authentication required.

Request body

{
  "idea": string,          // required — your startup idea
  "stage"?: string,        // optional — e.g. "just an idea", "MVP"
  "targetMarket"?: string, // optional — e.g. "SMBs", "Gen Z"
  "traction"?: string      // optional — e.g. "100 users", "$5k MRR"
}

Response

{
  "tier": "roasted" | "needs-work" | "decent" | "ship-it",
  "verdict": string,        // one-line kill-shot or green flag
  "survival_rating": number, // 1–10
  "red_flags": string[]     // top failure reasons
}

Rate limit

1 request per IP per day. Exceeding returns 429 Too Many Requests.

POST/api/roast/stream

Full Panel Stream

Runs the full 4-agent panel (Market, Tech, Finance, Timing) with live market data and streams results as Server-Sent Events. Development-only endpoint. In production, full panel roasts are generated via the Bitcoin payment flow — see the Agent API below.

Request body

{
  "idea": string,           // required
  "stage"?: string,
  "targetMarket"?: string,
  "traction"?: string,
  "isPublic"?: boolean      // default true — appear on leaderboard
}

SSE stream events

// Agent finding (emitted per agent)
data: { "type": "finding", "agent": string, "emoji": string,
        "finding": string, "live": boolean }

// Verdict synthesis starting
data: { "type": "verdict" }

// Stream complete
data: { "type": "done", "id": string, "roastText": string,
        "panelFindings": AgentFinding[] }

// Error
data: { "type": "error", "message": string }

AgentFinding shape

{
  agent: string,   // e.g. "Market Agent"
  emoji: string,
  finding: string,
  live: boolean
}

GET/api/agent

Agent API (x402)

Designed for autonomous AI agents. Self-describing when called with no parameters. When called with an idea query param, returns 402 Payment Required with BTC payment details. Once payment is detected on-chain, the roast generates automatically — poll /api/roast?id=<id> for the result.

Schema response (no params)

GET /api/agent
→ 200 { description, params, pricing, ... }

Payment request (with idea)

GET /api/agent?idea=<encoded>&stage=<...>&market=<...>&traction=<...>

→ 402 {
  "payment": {
    "address": string,   // BTC address
    "amount_btc": string,
    "amount_sats": number,
    "amount_usd": string
  },
  "roast_id": string     // poll with this ID
}

Structured result (after completion)

GET /api/roast?id=<roast_id>

→ 200 {
  "status": "complete",
  "roast_text": string,
  "panel_findings": AgentFinding[],
  "structured": {
    "survival_rating": number,
    "tier": string,
    "verdict": string,
    "red_flags": string[],
    "pivot": string
  }
}

GET/api/roast?id=<roast_id>

Poll for Result

Polls for the status and result of a roast by ID. Used after initiating a BTC payment via the Agent API. Poll every 10–15 seconds until status is "complete" or "failed".

Response

// Pending
{ "status": "pending" }

// Complete
{
  "status": "complete",
  "roast_text": string,
  "panel_findings": AgentFinding[]
}

// Failed
{ "status": "failed" }

GET/api/btc-price

BTC Price

Returns the current BTC equivalent of the roast fee in real-time. Price quotes expire after 10 minutes. No parameters required.

Response

{
  "amount_btc": string,   // e.g. "0.00002341"
  "amount_sats": number,  // e.g. 2341
  "amount_usd": string    // e.g. "2.00"
}

For machine-readable docs, see /llms.txt — formatted for LLM consumption.