Flashpoint.AIFlashpoint.AIdocs

API Reference

The Flashpoint.AI MCP server exposes five direct tools plus a chat tool that hands off to the full orchestrator. Every tool runs through the same identity model — see Authentication — and respects per-team scoping.

Endpoint: https://api.flashpoint.ai/mcp (production) · https://mcp-staging.flashpoint.ai/mcp (staging)

Transport: MCP Streamable HTTP over POST. Each request is a JSON-RPC envelope:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "<tool-name>", "arguments": { … } }
}

You don't normally hand-craft these — MCP clients (Claude Desktop, Claude Code, ChatGPT, Cursor, etc.) handle the protocol for you.

When to use which tool

GoalToolBrain
Anything about a survey: plan, design, quotas, translate, QA, publish, recruit paid respondents, distribute, analyze, exporttool_surveyWraps the surveys agent — multi-turn LLM with ~150 internal tools and confirm gates. Every one of them is listed in the MCP capability reference
Synthetic respondents: build a persona panel, run it through a survey, or recruit paid respondentspanelDirect dispatch (recruit delegates to the surveys agent)
Population stats for a placedemographicsDirect dispatch — single worker call
Native .pptx with editable chartspresentationDirect dispatch
Settle an x402 panel payment (wallet agents only)payment_confirmationDirect
Multi-domain plan in one shot, or orchestrator-only capabilities (ad experiments, research scoping, team files, maps, asking a panel a question)chatFull orchestrator — picks tools, runs them, narrates

Direct-dispatch tools are faster (one worker, no second LLM planning loop). Send all survey work to tool_survey, not chat — the surveys agent already plans and runs multi-step survey flows itself, and routing it through chat adds a redundant LLM hop and a longer handshake.

The older tool names surveys_agent, create_panel, and get_demographics are still registered as deprecated aliases of tool_survey, panel(action="create"), and demographics.


tool_survey

The single entry point for anything survey-related. Hand it a natural-language brief; the surveys agent runs its own multi-turn loop (planning plus a large internal toolset) and takes the next steps itself. You do not chain individual operations.

What it covers

AreaCapabilities
Plan & researchClarify the objective, research the market / audience / competitors, propose a blueprint before building; start from a template or save a survey as one
Design20+ question types (single, multi, grids, ranking, MaxDiff, conjoint / CBC, image compare, spatial allocation, thermometer, sliders, open ends, contact form, AI-moderated interview); blocks with rotation / randomization, answer lists, skip and display logic, piping, loops, URL variables, redirect URLs, derived values, exclusive options, data validation
Quotas & sample sourcesQuota cells, least-fill, quota sheets, progress / reconcile / export; bring-your-own sample sources with per-vendor links and redirects; first-party and custom panels
LanguagesAdd survey languages, machine-translate, review or set individual translations
Validation & QAsurveycheck logic prover, publish readiness, DSL validation, QA rounds with findings, walk a respondent path, field report, client review link
Launch & lifecyclePublish, pause, resume, complete, clone, transfer; version history, compare, restore, undo
Paid recruitmentProlific, Dynata, Cint: browse filters and markets, get a quote, then on confirmation a secure checkout link; panel status / pause / resume after launch
DistributionEmail lists and templates, invitations, reminders, send to a panel, send reports
Data qualitySpeeders, straightliners, quality summary, exclude responses, generate test data
Analysis & exportsFrequencies, crosstabs with stat tests, NPS, open-end themes, AI summaries and key takeaways; conjoint analytics (market simulator, willingness-to-pay, sensitivity, segments, product optimizer, share link); CSV / XLSX / DOCX / PDF exports; results dashboard
CollaborationComments on questions, resolve threads

Interactive cards (plan, approval, results dashboard, conjoint simulator, checkout) render in the Flashpoint.AI web app, not in your assistant. The text reply carries the substance, and every MCP conversation is also visible at app.flashpoint.ai afterwards.

Confirm pattern

Money and destructive actions (publish, delete, send emails, paid recruitment) are never performed on the first ask. The agent replies asking you to confirm; your assistant relays that, and you call again on the same conversation_id with the confirmation (e.g. "confirm"). Nothing is charged without that explicit second step. For paid recruitment the confirmation returns a hosted Stripe Checkout link you open in a browser.

Parameters

NameTypeRequiredDescription
briefstringyesWhat you want done, in natural language — a build spec, an edit, a recruitment request, an analysis ask, an export, a confirmation
survey_idstringnoPass to act on an existing survey; omit to create a new one
conversation_idstringnoPass the value returned by a previous call to continue the same thread. Required to keep context across build → recruit → analyze and to satisfy a confirm step. Omit on the first call and the server mints one

Returns

The agent's result blob (typically includes the relevant survey_id), with the conversation_id echoed back so follow-up calls can thread:

{
  "conversation_id": "<uuid>",
  "survey_id": "<uuid>",
  "...": "..."
}

The call may take 60–600s. Clients that send a progressToken receive progress notifications for each agent step while it runs.

See Surveys for the broader survey model.


panel

Manage respondent samples — synthetic personas and paid recruits. Routing is by action:

actionWhat it doesRequired
createBuild a synthetic panel of AI-generated personas (max 200). Returns a panel_idname, num_respondents, research_objective
create_and_runBuild a fresh synthetic panel and run it through a survey in one call. Progress streams via MCP progress notifications; long runs (~45 min) survive idle timeoutsname, num_respondents, research_objective, survey_id
runNot supported on the direct path — an existing panel's personas live in the orchestrator's artifact store. Use create_and_run, or ask chat to run the panel by id—
recruitReal paid respondents from Prolific / Dynata / Cint. Delegates to the surveys agent's quote → confirm → checkout flowsurvey_id (for a quote) or request (free-text catalog browse)

Parameters

NameTypeRequiredDescription
actionstringyescreate, create_and_run, run, or recruit
namestringcreatePanel name
num_respondentsintegercreatePersona count, 1–200
research_objectivestringcreateWhat the panel is for — shapes the personas
contextstringnoExtra grounding, e.g. real distributions from demographics
audienceobjectnoStructured audience targeting
survey_idstringcreate_and_run, recruitSurvey to run or to quote recruitment for
providerstringnoprolific, dynata, or cint
requeststringnoFree-text catalog question for recruit, e.g. "what Prolific filters are available?"
conversation_idstringnoThread follow-up recruit calls (quote → confirm)

Returns

A worker ToolResult dict — status, result, error, and timing. create_and_run returns both the panel_id and the run result.


demographics

Population, age, race, gender, education, and income distributions with AI-powered insights. US locations are sourced from the US Census Bureau; international locations come from a curated city/country database.

Parameters

NameTypeRequiredDescription
locationstringyesA US zip code, city name, country, or any human-readable place
questionstringnoSharpen the response — e.g. "focus on adults 25–44 with a college degree"
audiencestringnoOverride the implied audience — e.g. "small-business owners"

Returns

A worker ToolResult dict — status, result, error, and timing.


presentation

Generate a native PowerPoint (.pptx) deck with editable charts.

Parameters

NameTypeRequiredDescription
titlestringyesDeck title
data_contextstringyesSurvey, analysis, or any text-form data the deck should be built from
custom_instructionsstringnoTone, brand notes, structure overrides
max_slidesintegerno — default 12Clamped to 2–30

Returns

A worker ToolResult dict. When S3 is configured the deck is uploaded and a download_url is returned; otherwise the raw .pptx is base64-encoded as pptx_base64.


payment_confirmation

Settle an x402 panel payment intent and trigger the panel launch. Autonomous wallet agents only — humans complete panel payment through the Stripe Checkout link the surveys agent returns, not through this tool.

Call it after tool_survey (or chat) returns an x402_payment_required envelope, passing the envelope's intent_id. The x402 middleware paywalls this tool by the intent's exact amount: the first call returns a 402 with the on-chain payment requirements (EIP-3009 on Base USDC); sign the authorization, retry with the X-PAYMENT header, and the facilitator settles the transfer. The panel starts launching once the settle succeeds.

NameTypeRequiredDescription
intent_idstringyesThe intent_id from the x402_payment_required envelope

chat

Send a message to Flashpoint.AI's server-side orchestrator and wait for the assistant's reply. The orchestrator decides what to do and returns when the turn is complete.

Use when you want a multi-domain flow planned in one shot (e.g. demographics + a synthetic panel + a presentation), or for capabilities that have no direct tool yet:

  • Ad and market experiments on Google, Meta, or LinkedIn Ads: build variants, run synthetic personas through them before spending budget, launch, and analyze campaign results
  • Research scoping: decide what to research, pick a methodology, draft a Statement of Work
  • Existing synthetic panels: ask a panel a single question, list the team's panels, run or calibrate a panel by id
  • Team file library: search and read the team's surveys, results, panels, and documents
  • Maps of places or regions

Do not route survey work here — use tool_survey.

Parameters

NameTypeRequiredDescription
messagestringyesWhat you want Flashpoint.AI to do, in natural language
conversation_idstringnoPass the value returned by a previous call to continue the same conversation. Omit to start a new thread

Returns

{
  "conversation_id": "<uuid>",
  "reply": "<assistant text — the full turn>"
}

The call blocks until the orchestrator finishes the turn (timeout 600s).


Pricing (wallet agents)

Humans signed in through OAuth are not charged per call — usage is covered by the Flashpoint.AI subscription. Autonomous wallet agents pay per call in USDC over x402 on Base; calling without payment returns a 402 with the terms. Defaults: chat $0.01, demographics $0.05, tool_survey $0.50, presentation $0.25, panel $0.50 (create), $0.60 (create_and_run), $0.50 (recruit). A call whose worker returns an error is not settled.


Discovery endpoints

For programmatic clients that need to spin up the OAuth flow:

PathWhat
GET /.well-known/oauth-protected-resourceRFC 9728 protected-resource metadata
GET /.well-known/oauth-authorization-serverRFC 8414 authorization-server metadata
POST /oauth/registerRFC 7591 dynamic client registration
GET /oauth/authorizeStandard OAuth 2.1 + PKCE entry point
POST /oauth/tokenAuthorization-code exchange

You shouldn't need to call any of these by hand if you're using a standard MCP client.

Surveys REST API

Most surveys operations are also available as a REST API directly against the surveys service. See Surveys › Build and the per-area pages (Lifecycle, Distribute, Analyze, Import & export) for endpoint paths and payloads.