SEsearchable
Projects

Create a project

Changed on

Create a project and set it up as the app's Add project flow does: the project on the workspace's plan cadence, its competitors, brand profile, default location and onboarding record, counted toward the workspace's project quota. It requires the same details the app asks for (brand name and summary, reach, country, at least one competitor); generatePrompts: true starts the app's prompt generation in the background, and the prompts are tracked within the prompt allowance. Requires a connection minted with the project:provision capability (not the bare write scope); a project-bound credential is refused outright, since creating a project is a workspace-level action. Supports Idempotency-Key replay; a reused key with a different body returns 409 idempotency_conflict instead of replaying the first project. A duplicate domain in the same workspace returns 409 duplicate_domain.

post/api/mcp/projects

Request

  • Base URL
    https://app.searchable.com
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

workspaceIdstring required

A workspace from GET /api/mcp/workspaces whose canCreateProjects is true.

domainstring required

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

brandNamestring required

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

brandSummarystring required

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

brandNameDisambiguationstring

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

reach'global' | 'national-global' | 'nationwide' | 'regional' | 'local' required

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

countrystring required

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

citystring

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

statestring

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

languagestring

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

brandAliasesstring[]

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

namestring

Project name; defaults to the brand name

descriptionstring
generatePromptsboolean required

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

Response

Project created.

successboolean required
promptGeneration'started' | 'not_requested'
notesstring[]

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.

Changes