Idea Launch

Set one generated variant as the idea's hero image.

Args:

• ideaId (string)

• jobId (string): a succeeded image job

• selectedResultId (string): the variant id from that job's results

Returns: { ideaId, imageUrl, applied }.

Costs no Ad Run credit and consumes no AI turn.

Create a new idea in the signed-in user's workspace.

Starts a validation test for a new idea, or — with websiteUrl — records a product that has already shipped.

Args:

• name (string): short name for the idea

• summary (string): a few sentences on what it is, who it is for, and the problem it solves

• websiteUrl (string, optional): an existing live URL to send ad traffic to

Returns: { id, name, summary, publicSlug, heldForReview, workbenchUrl, nextStep }.

Creates nothing on an ad platform and spends nothing. If the content is flagged by moderation the idea is still created but held from public surfaces, reported as heldForReview.

Generate suggested brief fields for an idea: target customer, why they'd care, the current alternative, and the primary market.

Returns suggestions without saving. Nothing on the idea changes until brief fields are saved.

Returns: { ideaId, saved: false, suggestions: { targetCustomer, whyTheydCare, currentAlternative, primaryMarket, signupIncentive, notesToAvoid }, note }.

Consumes one of the idea's AI generation turns. Costs no Ad Run credit.

Generate the ad creative for an idea: tagline, primary and secondary ad text, an image prompt, and sign-up page copy.

Requires a complete brief (target customer, why they'd care, current alternative and primary market); returns an error naming the missing fields otherwise.

Args:

• ideaId (string)

• save (boolean): when true, writes the generated copy onto the idea. Defaults to false, which returns the copy without saving it.

Returns: { ideaId, saved, assets: { tagline, adPrimaryText, adSecondaryText, imagePrompt, signupLearnMoreMarkdown, signupThemePreset }, note }.

It does NOT write the sign-up page headline, description or CTA; those are separate brief fields, and the conversion-destination check requires them.

Consumes one of the idea's AI generation turns. Costs no Ad Run credit.

Start generating hero image variants for an idea's ad. Runs in the background.

Args:

• ideaId (string)

• prompt (string, optional): defaults to the idea's saved image prompt

Returns: { job: { id, status, prompt, variantCount, results }, note }.

The job finishes in the background; its variants are available once its status is 'succeeded'. Consumes one of the idea's AI generation turns. Costs no Ad Run credit.

Show the signed-in user's Ad Run credit balance and whether they can start a new Ad Run.

Returns: { email, availableAdRunCredits, requiredAdRunTokens, canStartAdRun, buyUrl }.

Reports Ad Run credits and the published list price only. It never reports what a campaign costs to run.

Get one Ad Run with its full lineage — the original run, any boosts derived from it, and the combined readout across the lineage.

Gives the detail behind a single experiment, including how boosts compare to the original.

Returns: { run, lineage: { rootRunId, bestCompletedRunId, overallReadout, runs, activeBoostRunId } }.

What Idea Launch does, what a market read contains, and what it costs. Requires no account.

Returns: product summary, the two jobs it serves (validate an idea, or get ads running for something already shipped), the four steps, what the market read reports, and pricing.

Get one idea in detail: setup progress, a readiness checklist for launching an Ad Run, active runs, and recent runs.

Answers "is this idea ready to test?": each failing check comes back with the specific fix.

Returns: { idea, readiness: [{ key, label, ready, fix }], readyToLaunch, activeRuns, recentRuns }.

Returns an error if the idea id does not belong to the signed-in user.

Check the status of a hero image generation job and list any finished variants.

Returns: { job: { id, status, prompt, variantCount, error, results: [{ id, url, prompt }] } }.

Status is one of queued, running, succeeded, failed, cancelled. Each result id identifies one variant that can be set as the hero image.

Get the decision readout for one Ad Run: validation score and band, confidence, the signals behind the score, and the recommended next move.

Returns: { run, lineage: { rootRunId, bestCompletedRunId, overallReadout, runs, activeBoostRunId } }.

An Ad Run measures market interest in a specific positioning — message, offer, and landing experience. It is evidence about that positioning, not proof that the idea will succeed. A provisional readout is marked as such.

Get the chronological event log for an Ad Run: provisioning steps, status changes, review holds, and errors.

Answers "why is my run not live yet?". A run held at pending_review is waiting on an Idea Launch review; nothing has been charged and nothing has been sent to the ad platform yet.

Returns: { total, count, offset, items: [{ id, type, message, createdAt }], has_more, next_offset }.

List every Ad Run for an idea, with status, platform, market read, click-through rate, and signups.

Shows the history of experiments on an idea, with each run id.

Returns: { total, count, offset, items: [PublicRun], has_more, next_offset }.

Reports CTR, traffic, and signups — the same signals the Idea Launch app shows.

List the ideas in the signed-in user's workspace, with setup progress, run counts, signup counts, and the aggregate market read where one exists.

Returns: { total, count, offset, items: [{ id, name, status, setupCompletionLabel, totalRunCount, activeRunCount, waitlistSignupCount, readout }], has_more, next_offset }.

Returns no results if the user has not created an idea yet.

List the signups an idea has captured, optionally narrowed to one Ad Run.

Email addresses are withheld by default and only the domain is returned. Full addresses are returned only when includeEmails is true.

Args:

• ideaId (string)

• runId (string, optional): only signups attributed to this Ad Run

• includeEmails (boolean): return full addresses (default: false)

Returns: { total, count, items: [{ id, email, emailDomain, source, runId, createdAt }] }.

Check whether an idea is ready to test, and preview what would run.

This creates nothing and spends nothing. It reports every launch gate with a specific fix, and — when the account has an Ad Run credit — previews the platform that would be chosen, why, the market, and the inferred audience. Starting the run is confirmed in the Idea Launch app; there is no tool that can charge the account.

Returns: { ideaId, readiness: [{ key, label, ready, fix }], readyToLaunch, availableAdRunCredits, canStartAdRun, plan, launchUrl, note }.

The platform and audience preview costs paid inference, so it is only produced when a credit is available. Readiness checks are always returned.

Show where ad traffic will land, and the copy on that page.

For an idea in waitlist mode this returns the generated sign-up page URL plus its headline, description and call to action. For an idea pointed at the founder's own site it returns that URL instead.

Returns: { ideaId, mode, url, copy, note }.

Save one or more brief fields on an idea. Only the fields you pass are changed; the rest are preserved.

Args (all optional, at least one required): targetCustomer, whyTheydCare, currentAlternative, primaryMarket, signupIncentive, notesToAvoid, conversionMode, externalDestinationUrl, tagline, adPrimaryText, adSecondaryText, signupPageHeadline, signupPageDescription, signupPageCtaLabel.

primaryMarket must be one of US, CA, GB, AU, GL. conversionMode must be 'waitlist' or 'external_url'.

Returns: { ideaId, updatedFields, setup, briefReady }.