Skip to main content
POST
Create a pitch

Authorizations

Authorization
string
header
required

A Searchable API key, created under Manage Account → Integrations → API Keys. Send as Authorization: Bearer sea_xxxxx. Every key carries one or more scopes (read, write, admin) and may optionally be bound to a single project — see Getting started.

Headers

Idempotency-Key
string

Optional client-generated key (e.g. a UUID). Retrying with the same key within 24h replays the original stored response (X-Idempotent-Replay: true) instead of repeating the side effect. See Idempotency.

Body

application/json
workspaceId
string<uuid>
required

A workspace from GET /api/mcp/workspaces whose canCreateProjects is true and whose plan has pitches (GET /api/mcp/pitches shows canCreatePitches).

domain
string
required

The brand's website domain, e.g. example.com

brandName
string
required

The brand's name, as it's referred to in prompts and reports

brandSummary
string
required

2-3 sentences: what the brand sells, who it serves, and what makes it distinct

reach
enum<string>
required

Where the brand sells; national-global is a primary market plus international reach

Available options:
global,
national-global,
nationwide,
regional,
local
country
string
required

Where most customers are: an ISO 3166-1 alpha-2 code, e.g. GB

competitors
(string | object)[]
required

Direct competitors, each a website domain or {domain, name}

Required array length: 1 - 20 elements
generatePrompts
boolean
required

Start the app's prompt generation in the background (tracked prompts, within the workspace's pitch allowance)

brandNameDisambiguation
string

When the name is ambiguous, a short note on which brand this is; empty when the name is distinctive

city
string

The city, for regional or local reach, e.g. Austin. A state's name here is taken as the state. A US city in more than one state needs state, or it is not placed

state
string

The state, for regional or local reach: alone for the whole state (e.g. California), or with city for the state the city is in (e.g. Oregon for Portland). A US code such as TX works; elsewhere write the name

language
string

Language for the prompts, e.g. en-GB; defaults from the country

brandAliases
string[]

Other names the brand goes by, counted as mentions of it

Maximum array length: 25
name
string

Project name; defaults to the brand name

dryRun
boolean

Run the checks and return the preview without creating anything.

Response

Pitch created, or the preview of it for a dry run.

The pitch that was created, or, with dryRun: true, the preview of it.

pitch
object
required

One pitch as the Pitches tab shows it, worked out by the app's own rules. A converted pitch is a ConvertedPitchRecord instead.

success
boolean
required
promptGeneration
enum<string>
required
Available options:
started,
not_requested
location
object

The pitch's default location as saved: the country, a state (region with no city), or a city in its state.

notes
string[]

Present only when a state or city that was sent could not be placed: a state that matches no known state; a city that was not recognised; a US city found in more than one state; a state or city that could not be checked, because the lookup failed or did not answer, which is never reported as not recognised. The default location is then the whole country.