Developer API

Manage your AI setters programmatically.

SetterFlow ships a remote Model Context Protocol server so you — or an AI agent — can list, create, and edit your own AI setters from Claude Code, Cursor, or any MCP client. Every request is scoped strictly to the account that minted the key.

POST https://www.setterflow.com/api/mcpStreamable HTTPStateless

01Quickstart

Mint a key, then call the endpoint

Three steps from zero to a live tool call. Most people skip curl and point Claude Code or Cursor at the same URL.

1Mint a key
In the dashboard, open Settings → API Keys and create a key with a read or read + write scope. The full sf_… token is shown once — copy it immediately.
2Send Bearer auth
Send it on every request as a Bearer token: Authorization: Bearer sf_…
3Call JSON-RPC
Speak JSON-RPC over Streamable HTTP: initialize, list tools, then call one. The transport is stateless — each request is authenticated on its own.

curl · streamable http

# 1) Initialize the session (handshake)
curl -sS https://www.setterflow.com/api/mcp \
  -H "Authorization: Bearer sf_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

# 2) List the tools your key can call
curl -sS https://www.setterflow.com/api/mcp \
  -H "Authorization: Bearer sf_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 3) Call a tool (list your own chatbots)
curl -sS https://www.setterflow.com/api/mcp \
  -H "Authorization: Bearer sf_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"list_chatbots","arguments":{}}}'

Client config snippets live in docs/mcp.md.

02Scopes

Two coarse scopes. Nothing in between.

A write key does not implicitly grant read — grant both if a single key should do everything.

read

22 tools

Read-only tools — list and inspect your data. Safe to hand to something that should only look, never change.

write

27 tools

Every mutating tool (create / update / delete / configure). A write key can change everything you own — treat it like a password.

03Tool catalog

49 tools, grouped by area

Generated directly from the live server registry — it always matches what your key can call.

Account

3 tools

Who you are and your account posture.

whoamiread

Return the authenticated caller identity (userId + granted scopes). No database access.

No arguments

get_accountread

Get the caller's own account (identity + subscription posture).

No arguments

update_profilewrite

Update the caller's own profile (full_name only).

Arg	Type	Required
`full_name`	string	required

Chatbots

5 tools

Create, read, update, and delete your AI setters.

list_chatbotsread

List the caller's own chatbots (AI setters).

No arguments

get_chatbotread

Get one chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required

create_chatbotwrite

Create a chatbot (AI setter) owned by the caller. owner_id is forced server-side.

Arg	Type	Required
`name`	string	required
`website_url`	string	required
`business_context`	string	required
`system_prompt`	string	required
`model`	string	optional
`status`	enum(active \| inactive)	optional

update_chatbotwrite

Update a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required
`name`	string	optional
`website_url`	string	optional
`business_context`	string	optional
`system_prompt`	string	optional
`model`	string	optional
`status`	enum(active \| inactive)	optional

delete_chatbotwrite

Delete a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required

Appearance & widget config

2 tools

The widget customization blob — colors, launcher, proactive teaser, Articles tab, and the invitation layer — plus the logo URL.

get_bot_configread

Read a chatbot's widget config (customization JSONB + logo_url) for a bot the caller owns. Null sub-objects mean unset (not default-filled).

Arg	Type	Required
`chatbotId`	string	required

update_bot_configwrite

Update a chatbot's widget config (read-merge-write). Send only the top-level customization keys you want to change; omitted top-level keys are preserved. WARNING: a sub-object you include (proactive / articlesTab) REPLACES the stored one wholesale, so send the FULL sub-object with all its fields. logo_url is a separate column (http/https URL, or null to clear) — not part of customization.

Arg	Type	Required
`chatbotId`	string	required
`customization`	object — see docs/mcp.md	optional
`logo_url`	string (http/https URL)	optional

Setter config (lead capture)

2 tools

Lead-capture settings — industry template, qualification questions, and collected fields.

get_lead_settingsread

Read lead-capture settings for a chatbot the caller owns (null if unconfigured).

Arg	Type	Required
`chatbotId`	string	required

configure_lead_settingswrite

Configure lead-capture for a chatbot the caller owns. Expands the named industry template server-side; overrides are optional.

Arg	Type	Required
`chatbotId`	string	required
`industry`	enum(aesthetics \| dental \| real_estate \| home_services \| coaching \| custom)	required
`enabled`	boolean	optional
`qualification_questions`	array	optional
`collect_fields`	array	optional
`notification_email`	string	optional
`notification_webhook_url`	string	optional

Knowledge base

4 tools

Plain-text documents that your setter can answer from.

add_knowledge_documentwrite

Add a plain-text knowledge document to a chatbot the caller owns. Live in the bot's knowledge base on the next chat turn; counts against the document quota.

Arg	Type	Required
`chatbotId`	string	required
`title`	string	required
`content`	string	required

list_documentsread

List knowledge-base documents for a chatbot the caller owns (crawler-projected docs excluded; document text not included).

Arg	Type	Required
`chatbotId`	string	required

get_documentread

Get one knowledge-base document (including its text content) on a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required
`documentId`	string	required

delete_documentwrite

Delete a knowledge-base document on a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required
`documentId`	string	required

Website & crawl

7 tools

Register website sources, trigger background crawls that feed the knowledge base, and curate which crawled pages appear in the widget Articles tab.

add_website_sourcewrite

Add a website source to a chatbot the caller owns (idempotent on URL). The URL must be an http/https address. This only registers the source; call trigger_crawl to start crawling (which runs in the background — poll get_crawl_status).

Arg	Type	Required
`chatbotId`	string	required
`url`	string (http/https URL)	required

configure_website_sourcewrite

Configure an existing website source's crawl behavior for a chatbot the caller owns. `refresh_interval_minutes` sets the auto-recrawl cadence. `url_filter` (with `include` and/or `exclude` arrays of URL substrings/patterns) limits which pages are crawled. Only the fields you send are changed; omitted fields are preserved. The sourceId must belong to the chatbot, else 'not found'. Returns the source's config after the update. (Use add_website_source to create a source, trigger_crawl to start a crawl.)

Arg	Type	Required
`chatbotId`	string	required
`sourceId`	string	required
`refresh_interval_minutes`	number	optional
`url_filter`	object — see docs/mcp.md	optional

trigger_crawlwrite

Trigger a crawl for a chatbot the caller owns. Provide a sourceId to crawl one source (it must belong to the chatbot, else 'not found'), or omit it to crawl all of the chatbot's sources. Crawling runs in the background — poll get_crawl_status for progress.

Arg	Type	Required
`chatbotId`	string	required
`sourceId`	string	optional

list_website_sourcesread

List the website sources for a chatbot the caller owns (each with its seed URL, refresh cadence, and current crawl status).

Arg	Type	Required
`chatbotId`	string	required

get_crawl_statusread

Poll the crawl status for a chatbot the caller owns — one status row per source (last crawl status/time, latest job status, page counts). Use this to track a crawl started by trigger_crawl.

Arg	Type	Required
`chatbotId`	string	required

list_source_articlesread

List a crawled source's article/content pages for a chatbot the caller owns — each with its storage_path (the id used by set_article_curation), title, url, and current show_in_article_tab flag. Paginated (limit/offset) and optionally filtered by search. Use this to discover which pages exist before curating the widget Articles tab.

Arg	Type	Required
`chatbotId`	string	required
`sourceId`	string	required
`limit`	number	optional
`offset`	number	optional
`search`	string	optional

set_article_curationwrite

Show or hide ONE crawled page in the widget's public Articles tab, for a chatbot the caller owns. Pass the page's storage_path (from list_source_articles) and enabled (true = show, false = hide). NOTE: the Articles tab itself must also be enabled via update_bot_config (customization.articlesTab.enabled) for curated pages to render to visitors.

Arg	Type	Required
`chatbotId`	string	required
`storage_path`	string	required
`enabled`	boolean	required

Follow-ups

4 tools

Automated follow-up message templates.

list_followupsread

List follow-up message templates for a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required

create_followupwrite

Create a follow-up template on a chatbot the caller owns. Requires the followUpSequences feature. delay_minutes is 5..1380 (defaults to 120).

Arg	Type	Required
`chatbotId`	string	required
`trigger`	enum(no_reply_2h \| hot_lead_stall \| appointment_reminder)	required
`message_template`	string	required
`delay_minutes`	number	optional
`is_active`	boolean	optional

update_followupwrite

Update a follow-up template on a chatbot the caller owns. Send only the fields you want to change.

Arg	Type	Required
`chatbotId`	string	required
`followupId`	string	required
`trigger`	enum(no_reply_2h \| hot_lead_stall \| appointment_reminder)	optional
`message_template`	string	optional
`delay_minutes`	number	optional
`is_active`	boolean	optional

delete_followupwrite

Delete a follow-up template on a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required
`followupId`	string	required

Integrations

10 tools

CRM, calendar, and social connections (read + disconnect — connecting a channel is OAuth-only).

list_crm_connectionsread

List CRM connections for a chatbot the caller owns. Secret api_key is never returned.

Arg	Type	Required
`chatbotId`	string	required

create_crm_connectionwrite

Create a CRM connection on a chatbot the caller owns. Requires the crmIntegration feature.

Arg	Type	Required
`chatbotId`	string	required
`crm_type`	enum(gohighlevel \| hubspot \| slack \| webhook \| kommo)	required
`api_key`	string	required
`auto_push_enabled`	boolean	optional
`push_on_status`	enum(hot \| warm \| any)	optional

update_crm_connectionwrite

Update an existing CRM connection's push behavior on a chatbot the caller owns: auto_push_enabled (on/off), push_on_status (hot | warm | any — which leads get pushed), and is_active. The api_key credential can't be changed here — rotate it by deleting and re-creating the connection. Only the fields you send change. The secret api_key is never returned.

Arg	Type	Required
`chatbotId`	string	required
`connectionId`	string	required
`auto_push_enabled`	boolean	optional
`push_on_status`	enum(hot \| warm \| any)	optional
`is_active`	boolean	optional

delete_crm_connectionwrite

Delete a CRM connection on a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required
`connectionId`	string	required

list_calendar_connectionsread

List calendar connections for a chatbot the caller owns. Access/refresh tokens are never returned.

Arg	Type	Required
`chatbotId`	string	required

delete_calendar_connectionwrite

Delete calendar connections for a chatbot the caller owns (calendar create is OAuth-only, not available via MCP).

Arg	Type	Required
`chatbotId`	string	required

configure_availabilitywrite

Set booking availability on a chatbot's ACTIVE calendar connection (a bot the caller owns) — the write side of the availability list_calendar_connections returns. `days` REQUIRES all seven keys (mon,tue,wed,thu,fri,sat,sun), each { start, end (24-hour "HH:MM"), enabled }; a disabled day is closed. slotDuration and bufferMinutes are minutes; timezone is an IANA name (e.g. "Europe/Nicosia"). This REPLACES the stored availability wholesale. Requires a calendar already connected via OAuth — a bot with no active calendar returns 'not found'.

Arg	Type	Required
`chatbotId`	string	required
`availability_config`	object — see docs/mcp.md	required

list_social_connectionsread

List social (Facebook Messenger / Instagram) connections for a chatbot the caller owns. The Meta page access_token is never returned.

Arg	Type	Required
`chatbotId`	string	required

disconnect_social_connectionwrite

Disconnect (delete) a social connection on a chatbot the caller owns. Connecting a channel is Meta OAuth and not available via MCP.

Arg	Type	Required
`chatbotId`	string	required
`connectionId`	string	required

set_social_auto_replywrite

Turn auto-reply on or off for one social (Messenger / Instagram) connection on a chatbot the caller owns. When off, the bot stops answering that channel automatically so a human can take over the inbox. Returns the updated connection (access_token never included).

Arg	Type	Required
`chatbotId`	string	required
`connectionId`	string	required
`enabled`	boolean	required

Analytics

1 tool

Account-level and per-bot usage counters and daily stats.

get_analyticsread

Read analytics. Omit chatbotId for account-level usage (messages, documents, chatbots, social connections for the current period). Provide a chatbotId you own for that bot's message count, last message time, and recent daily stats.

Arg	Type	Required
`chatbotId`	string	optional

Conversations

2 tools

Read widget conversations and their messages.

list_conversationsread

List widget conversations for a chatbot the caller owns (newest first). Returns id, session_id, attribution (the owner's own marketing metadata), and created_at. Social (Messenger/Instagram) conversations are not exposed via MCP yet — widget only.

Arg	Type	Required
`chatbotId`	string	required
`limit`	number	optional
`offset`	number	optional

get_conversationread

Get one widget conversation and its messages (capped at 100, oldest first) — resolved only after verifying the caller owns the chatbot the conversation belongs to. A conversation you do not own returns forbidden/not found. Widget conversations only.

Arg	Type	Required
`conversationId`	string	required

Leads

3 tools

Read the leads your setters have captured.

list_leadsread

List leads across the caller's own chatbots (or scoped to one chatbot). Cross-tenant leads never appear.

Arg	Type	Required
`chatbot_id`	string	optional
`status`	enum(hot \| warm \| cold \| converted \| lost)	optional
`limit`	number	optional
`offset`	number	optional

get_leadread

Get one lead by id, only if the caller owns the chatbot the lead belongs to.

Arg	Type	Required
`leadId`	string	required

update_leadwrite

Update a lead's status (hot | warm | cold | converted | lost) and/or notes — the only mutable fields (everything else is captured from the conversation). Only if the caller owns the chatbot the lead belongs to. Pass notes as a string to set it, or null to clear it. Send at least one field.

Arg	Type	Required
`leadId`	string	required
`status`	enum(hot \| warm \| cold \| converted \| lost)	optional
`notes`	string	optional

Widget

2 tools

The ready-to-paste embed snippet, plus the origin allowlist that controls which sites may embed a bot.

set_allowed_originswrite

Set the widget origin allowlist for a chatbot the caller owns — which website origins may embed and talk to this bot. Pass an array of http/https ORIGINS (scheme://host[:port], no path), e.g. ["https://www.example.com","https://example.com"]; list www and apex separately (exact match, no wildcards). An EMPTY array clears the allowlist and makes the widget embeddable from ANY origin (the default). Entries are canonicalized server-side; an invalid entry rejects the whole call. Read the current value via get_chatbot (allowed_origins).

Arg	Type	Required
`chatbotId`	string	required
`allowed_origins`	array	required

get_widget_snippetread

Get the ready-to-paste HTML embed snippet for a chatbot's widget (a bot the caller owns). Paste it before </body> on the target site.

Arg	Type	Required
`chatbotId`	string	required

Other

4 tools

list_custom_actionsread

List Custom Actions (tenant-configured HTTP tools the bot can call mid-conversation) for a chatbot the caller owns. The encrypted secret is never returned — only has_secret.

Arg	Type	Required
`chatbotId`	string	required

create_custom_actionwrite

Create a Custom Action on a chatbot the caller owns. Define name (snake_case), description (drives when the model calls it), kind (read|write), parameters (JSON Schema for the args the model extracts), and request ({method,url,headers,body} — {{args.x}} and {{secret}} are interpolated at call time). secret is encrypted at rest and injected into headers, never shown to the model. response_map whitelists which response fields reach the model (everything else, including PII, is dropped). Optionally set allowed_hosts (host allowlist) and timeout_ms.

Arg	Type	Required
`chatbotId`	string	required
`name`	string	required
`description`	string	required
`kind`	enum(read \| write)	optional
`parameters`	record	optional
`request`	object — see docs/mcp.md	required
`secret`	string	optional
`allowed_hosts`	array	optional
`response_map`	record	optional
`confirmation_template`	string	optional
`timeout_ms`	number	optional
`is_active`	boolean	optional

update_custom_actionwrite

Update a Custom Action on a chatbot the caller owns (double-fenced on id + chatbot_id). Only the fields you send change. Pass secret to rotate the credential (re-encrypted); pass is_active:false to disable it without deleting.

Arg	Type	Required
`chatbotId`	string	required
`actionId`	string	required
`name`	string	optional
`description`	string	optional
`kind`	enum(read \| write)	optional
`parameters`	record	optional
`request`	object — see docs/mcp.md	optional
`secret`	string	optional
`allowed_hosts`	array	optional
`response_map`	record	optional
`confirmation_template`	string	optional
`timeout_ms`	number	optional
`is_active`	boolean	optional

delete_custom_actionwrite

Delete a Custom Action on a chatbot the caller owns.

Arg	Type	Required
`chatbotId`	string	required
`actionId`	string	required

04Recipe

Turn on the invitation layer

The ambient, page-aware invitation is part of the widget customization, so a write key configures it through update_bot_config — no new tool. Auto-detect finds your prices and cards; smart copy writes a line per element. Flip it on with one call.

curl · streamable http

# Turn on the invitation layer for one of your chatbots.
# It lives in the widget customization, so you set it with the existing
# update_bot_config tool — no special endpoint. Sub-objects replace wholesale,
# so send the FULL invitation object (read get_bot_config first to preserve
# any custom elementTypes).
curl -sS https://www.setterflow.com/api/mcp \
  -H "Authorization: Bearer sf_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call",
       "params":{"name":"update_bot_config","arguments":{
         "chatbotId":"YOUR_CHATBOT_ID",
         "customization":{"invitation":{
           "enabled":true,
           "rolloutPercent":100,
           "autoDetect":true,
           "smartCopy":true
         }}}}}'

Sub-objects replace wholesale — send the full invitation object, and read current state with get_bot_config first if you're preserving custom elementTypes.

05Limitations

A few capabilities are deliberately partial

Known edges, called out so you don't discover them mid-build.

OAuth connect is not available
Establishing a new Google Calendar or Facebook/Instagram connection needs an interactive browser consent screen (human OAuth), so there is no connect tool. You can read and disconnect existing connections, but the initial connect happens once in the dashboard.
Logo is a URL, not a file
update_bot_config accepts logo_url as an http/https URL string only — there is no binary/image upload over MCP.
Conversations are widget-only
list_conversations and get_conversation return widget conversations only; social (Messenger / Instagram) transcripts are not exposed via MCP yet.

Own-tenant only

Ready to mint a key?

Operators: full deploy and security reference in docs/mcp.md. Everyone else — open the dashboard and create an API key.

Open the dashboard