Run Discord questionnaires from code
The Subo API lets you create conversational surveys and polls, generate their scripts with AI, open them to a Discord server or a web audience, and pull the answers back out. Every recipe below is a working request you can paste into a terminal.
Quickstart
Three steps: get a key, find your community id, make a call. Everything after that is the same pattern.
1. Create an API key
Open the Subo web app,
go to Community Account Tab → API Keys and create a key.
It is scoped to that one community and inherits your role, so you can
optionally cap it at Creator access. The key starts with
sbo_live_ and is shown once, so store it before closing the dialog.
Send it on every request:
X-API-Key: sbo_live_xxxxxxxxxxxxxxxxxxxxxxxx 2. Find your community id
Almost every endpoint is nested under a community. List the ones your key can reach:
curl "https://api.subo.ai/v1/communities" \
-H "X-API-Key: $SUBO_API_KEY" For a Discord community the id is the server (snowflake) id, returned as a string.
3. Send a write request
Writes take an Idempotency-Key header holding a UUID v4. Retry
a failed request with the same key and Subo replays the original result
instead of creating a duplicate project.
-H "Idempotency-Key: $(uuidgen)" Recipe: generate a survey from a plain-English goal
This is the shortest path from nothing to a working survey, and the one
worth reaching for if you are writing an agent. Describe what you want to
learn in the intent field and Subo writes the script:
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Post-event feedback",
"type": "convo",
"intent": "Measure how members felt about the weekend tournament and collect suggestions for the next one",
"question_count": 6,
"quality": "quick",
"privacy_mode": "anonymous"
}'
The 201 response includes the generated script with its
blocks plus a credits_used figure. A few notes that save a round trip:
typeisconvofor a multi-question survey orpollfor a single question.-
qualityisquickordeep. Leave it out and a paid community gets a Deep draft, which typically costs ~24,000-48,000 credits against ~700 for Quick. Set it explicitly in automation. -
question_countis optional: leave it out and the model picks what the goal needs, capped at 20 and at your plan's limit.max_blocksis still accepted as a deprecated alias. -
factstakes plain text the draft should use as written: dates, line-ups, results, odds. Models do not know recent events and there is no web search. -
intent, an explicitscriptandsource_project_idare mutually exclusive. Send exactly one. -
AI generation spends bot credits. With an empty balance the call returns
402 payment_requiredrather than a partial survey. -
languagetakes any language name or code. Leave it out and Subo uses a language the intent names ("a poll in Tagalog"), then the community's.admin_languagesets the language of the draft's notes; when omitted it is inferred from the intent and the response'snoticessays so. -
The response's
draftobject carriesauthor_notes(what to check before opening), thedroppedandflaggedblocks, themodelandcredits_used. -
Want the plan step the dashboard shows (outline, up to three questions, facts
needed)?
POST /communities/{communityId}/projects/generate/planreturns it; send itsplan, youranswersand itssession_idwith the create call.
New projects start inactive. Nobody can answer yet, which gives you room to review or edit before opening it.
Recipe: write the script yourself
When you want exact control, send the blocks instead of an intent. Same endpoint, different field:
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Server health check",
"type": "convo",
"privacy_mode": "anonymous",
"script": {
"blocks": [
{
"type": "single_punch",
"title": "How often do you hang out here?",
"options": [
{ "value": "Every day" },
{ "value": "A few times a week" },
{ "value": "Rarely" }
]
},
{
"type": "open_text",
"title": "What would make this server better?"
}
]
}
}'
To replace the script of an existing project, PUT it whole. The
project has to be inactive:
PUT https://api.subo.ai/v1/communities/{communityId}/projects/{projectId}/script
Individual blocks have their own endpoints for surgical edits:
POST .../script/blocks to append,
PUT .../script/blocks/{blockId} to change one,
DELETE to drop it.
Required and optional questions. Every question block takes
required, true by default. required: false
gives the respondent a Skip button, on the web and in Discord. It
is ignored on content, action and calculated blocks, which take no answer, and
refused on file_upload, where upload.min_files: 0 does the
same job. (The field was accepted and ignored before November 2026; it now takes
effect.)
Asking for files. A file_upload block takes an optional
upload object: categories (any of images,
documents, audio, video,
archives), min_files (0 makes it optional),
max_files (1 to 10) and max_bytes per file (omitted means
the plan's limit). Without upload the block takes one image or
document and is required. Sending upload on another block type is a
400. Storing a file uses the community's credits, paid by the
respondent's upload, never by an API call; see
how credits work.
{
"type": "file_upload",
"title": "Attach a screenshot of the bug",
"upload": { "categories": ["images"], "min_files": 0, "max_files": 3 }
}
Skip logic is worth calling out. You can hand-write the raw
precondition mini-language, but the API also accepts a structured
show_when / hide_when object and compiles it into a
correct precondition for you. Prefer the structured form: it removes a
whole class of quoting and inversion mistakes.
Recipe: upload an image for a block or an invitation
Image fields (a block's image_url and thumbnail_url,
the invitation image) take any https image link, as they always have. When you
have a file instead, or a link that will not last (a Discord attachment link
stops working after about a day), upload it and Subo hosts its own copy:
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/images" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "file=@banner.png" Or send a link as JSON, and Subo downloads the image:
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/images" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/banner.png" }' Either way you get a 201:
{
"data": {
"url": "https://...",
"content_type": "image/png",
"bytes": 184213,
"width": 1600,
"height": 900,
"frames": 1
}
} Put data.url in a block's image_url or anywhere else an image goes.
- Creator role, like other script writes.
Idempotency-Keyis supported. - PNG, JPEG, GIF or WebP. Static images are resized to at most 2048 px on the longest side and their metadata is removed; animations are kept.
-
The size limit depends on the community's plan. A file over it gets
413 too_largewithmax_bytesand, when a bigger plan exists,upgrade: {plan, max_bytes}. -
A
urlmust be https on the public internet (default port, no credentials), with up to 3 redirects. KLIPY links are refused: put a KLIPY GIF's link in the image field as it is. -
On top of the key's rate limit, one person can upload
30 images per 10 minutes (
429 rate_limitedwithRetry-After). -
Refusals carry a stable
reason:too_large,empty,not_an_image,unsupported_type,too_many_pixels,too_many_frames,url_not_allowed,url_klipy,fetch_failed.503 unavailablemeans uploads are switched off, and502 upstream_errorthat storing the image failed (retry). - An uploaded image is deleted about 7 days after no project uses it.
Recipe: ask a rating, a scale, an NPS or a ranking
Four of the block types are ordered question types, and they behave
differently enough from the choice blocks to be worth their own section.
The thing to know first: they store the number the respondent
picked, not a reference to an option. That is what makes an
average, a distribution and a >= 4 condition work with
nothing configured.
The point range is min / max
Not part of the scale object. The scale object
carries whole-scale presentation only: icon
(numbers, stars or emoji) and the
endpoint anchors label_left, label_center and
label_right.
options means something different here
On a choice block, options are the answers. On a scale,
option.value is the point number as a string
and the option carries that point's emoji or
label. A plain star or number scale sends no options
at all. A label on every point is how you build a
Likert item.
// Rating with an emoji set: options ARE the per-point presentation
{ "type": "rating", "prompt": "How was the playtest build?",
"min": 1, "max": 5,
"scale": { "icon": "emoji" },
"options": [ { "value": "1", "emoji": "😖" }, { "value": "2", "emoji": "🙁" },
{ "value": "3", "emoji": "😐" }, { "value": "4", "emoji": "🙂" },
{ "value": "5", "emoji": "😍" } ] }
// Opinion scale with endpoint anchors (the semantic-differential shape)
{ "type": "opinion_scale", "prompt": "How was the pacing?",
"min": 1, "max": 7,
"scale": { "label_left": "Way too slow", "label_center": "Just right",
"label_right": "Way too fast" } }
// Likert item: a word on every point. The stored answer is still the number,
// so averages and >= conditions keep working.
{ "type": "opinion_scale", "prompt": "The tutorial explained the controls well.",
"min": 1, "max": 5, "answer_style": "select_menu",
"options": [ { "value": "1", "label": "Strongly disagree", "emoji": "😡" },
{ "value": "2", "label": "Disagree", "emoji": "🙁" },
{ "value": "3", "label": "Neutral", "emoji": "😐" },
{ "value": "4", "label": "Agree", "emoji": "🙂" },
{ "value": "5", "label": "Strongly agree", "emoji": "😍" } ] }
// NPS: send the type and nothing else.
{ "type": "nps", "prompt": "How likely are you to recommend us to a friend?" }
// Ranking: items are options, rank_top_n (NOT max) asks for a partial ranking
{ "type": "ranking", "prompt": "Rank these features by what you want first.",
"answer_style": "full_text", "rank_top_n": 3, "randomize_options": true,
"options": [ { "value": "Mod support", "emoji": "🛠️" },
{ "value": "Co-op mode", "emoji": "👥" },
{ "value": "New maps", "emoji": "🗺️" },
{ "value": "Ranked play", "emoji": "🏆" } ] } Anchors and per-point labels are mutually exclusive
Sending both returns a 400. Labelling every point already
names the ends, so pick one. nps refuses a custom range,
custom anchors and a select menu on the same grounds: an NPS you can edit
is a number you cannot compare with anyone else's. Its anchors are never
stored, only rendered, so every respondent reads the standard wording in
their own language.
Ranking uses rank_top_n, not max
On a multi_punch, max means the maximum number of
selections, so ranking gets its own field for "rank your top 3 of 10".
min and max are ignored when you update a ranking
so they cannot quietly rewrite it. A ranking takes 2 to 20 items, and a
respondent submits it complete or not at all.
randomize_options applies to every block with options and
returns a 400 on the three scale types, which are ordered by
definition. Turn it on for rankings: whichever item sits first gets tapped
first, and that bias lands in the average rank your report shows.
What comes back
In /responses, a scale answer has option_id: null
and value set to the point number. A ranking writes
one row per ranked item, with value set to the
rank position.
In /analysis, the three scales return their distribution with
value as the point number, because a caller is a
program. A ranking block returns a ranking array instead, with
average_rank, first_choice_count and
ranked_count per item, best first.
A lower average_rank is better, which inverts
the reflex every other metric trains, and it is computed only over the
respondents who ranked that item, so read it next to
ranked_count.
Recipe: open the project to an audience
Opening is what makes a project live. It is also where you choose the ways in: a post in a Discord channel, a web link, or both.
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects/$PROJECT_ID/open" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"delivery": {
"entry_points": [
{ "type": "discord_post", "answers_on": "discord" },
{ "type": "web_link", "enabled": true, "who": "anyone" }
],
"invitation": {
"post_channel_id": "123456789012345678",
"message": "Two minutes of your time, and you get the role."
},
"closing": {
"mode": "scheduled",
"time": "2026-09-01T18:00:00Z"
}
}
}'
That is a Discord post answered in Discord, plus an open link.
delivery.entry_points lists the ways into a project. Each has its
own rule, and the Discord post and the web link are on independently:
type | Fields | Who gets in, and how |
|---|---|---|
discord_post | enabled, answers_on, required_role_ids | Members of the community's Discord server press the post. On when the project has delivery.invitation.post_channel_id. |
web_link | enabled, who, sign_in_with, verified_source_ids, verified_sources, url | Anyone who has the link (url, same as delivery.share_url). who anyone: no sign-in. who signed_in: a sign-in with one of sign_in_with, the person is named and nothing is checked. who verified: a sign-in with one of verified_source_ids, membership checked. |
invitation | source, campaign_id, name, step_name, status | Read-only, on GET project: a journey step or a campaign that invites to the project. The invitation admits its member, whatever the post and the link say. |
Send only the entry points you change, matched on type; an omitted
field keeps its value. Projects read back the same list on create, update,
open and every project read, with verified_sources in place of
verified_source_ids.
-
answers_onon the Discord post.discord: members answer in Discord (thread or DM, seeanswer_surfacesbelow).web: the post hands each of them a personal link and they answer on the web as themselves, even with the web link off. Polls have the Discord post only, answered in Discord. -
who: "verified"checks membership. A Discord source checks server membership live, Twitch checks follows, YouTube checks subscriptions, Steam checks that the person owns the game (any-of: one is enough). Get the ids fromGET /communities/{communityId}/sources(see Audience Sources below). Turning the link on withoutwhomeansverifiedwith the community’s Discord server. -
who: "signed_in"names everyone, checks nothing. The respondent signs in with one ofsign_in_with(discord,twitch,google,steam) and answers as themselves; no server, follow or role is required, and nothing needs connecting first.googleis a Google account, not a YouTube channel. A platform Subo cannot offer yet is a400that lists the available ones. A newsigned_inlink withoutsign_in_withoffersdiscord. One answer per account: someone with two accounts can answer twice. Rewards (XP, roles, achievements) reach only respondents who sign in with Discord. -
who: "anyone"identifies only some respondents. Anyone already signed in to Subo with Discord is named, member of the server or not, and can be rewarded; everyone else is unidentified and cannot be. If nobody should be named, setprivacy_mode: "anonymous", which covers the Discord post too. - Required roles gate every Discord check.
required_role_ids(any-of, set ondiscord_post) is checked where a member presses the post and where someone verifies with Discord on averifiedweb link. It does not apply on ananyoneorsigned_inlink, nor to Twitch, YouTube or Steam sources. - Someone must be able to get in. A project with no post channel
opens without posting when its web link is on, or when a journey or campaign
invites to it. With no post, no link and no invitation, open returns
422 channel_required. With only the web link, nothing is posted: sharedelivery.share_url. -
delivery.share_urlis the web link whileweb_linkis on, andnullwhile it is off. -
delivery.audienceis deprecated. Itsparticipation/response_channelpair still works, and sending back the pair you read changes nothing, but it cannot describe a post answered in Discord beside a web link. Useentry_points, and never send both: that is a400.
Two more web_link entries: a signed-in link offering Discord, Twitch and Google, and a link for your Discord members and Twitch followers:
{ "type": "web_link", "enabled": true, "who": "signed_in", "sign_in_with": ["discord", "twitch", "google"] }
{ "type": "web_link", "enabled": true, "who": "verified", "verified_source_ids": [12, 34] }
To close early, call POST .../projects/{projectId}/close.
Audience Sources
A community’s connected sources are what a verified link
checks against. The community’s Discord server is always there.
GET /communities/{communityId}/sources lists them, each with
id, provider (discord, twitch,
youtube or steam), external_id,
display_name, status and connected_at. The
id is what verified_source_ids takes.
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/sources" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "steam", "app_id": 1145360 }'
Only a Steam game (its App ID, from the store page URL) can be connected through
the API, with an Admin key. Twitch and YouTube need an Admin to sign in with the
channel in the dashboard, under Settings > Networks. Disconnect a source with
DELETE /communities/{communityId}/sources/{sourceId}.
Colors are 6-digit hex without the #:
"e1287e", not "#E1287E". That covers the invite
embed's border_color and border_color_closed, and the
community's closing_embed_color and
xp_closing_embed_color. A leading # is accepted and
removed, and anything else is a 400 that names the field.
The community's rewards.xp_achievement_announcement sets where
achievement and role notices go, through
PUT /communities/{communityId}. It is a string:
"" turns notices off, "-1" sends a DM (falling back to
the member's private thread with Subo when their DMs are closed),
"-2" posts in that private thread, and a Discord channel id posts
in that public channel with a mention of the member. Any other value is a
400.
Choosing where the Convo happens
A member who presses a Discord post answered in Discord can answer in one of
three places, and Subo tries them in
order until one works. delivery.answer_surfaces sets that order:
{
"delivery": {
"answer_surfaces": ["dm", "web"]
}
} | Surface | Where the member answers |
|---|---|
dm | A direct message from the bot. Nothing is created in the server. |
thread | A private thread in your server, visible to them and your team. |
web | A browser link. Always works, so it ends the chain. |
Order is the fallback chain, first to last: ["dm", "web"] means
try a DM, and if their DMs are closed, hand them a link instead. Each surface
may appear once. Put web last — it cannot fail, so anything
listed after it is never reached. The API accepts such a chain rather than
rejecting it, so this one is on you to get right.
-
nullis the default and is not the same as an empty list. It means no override: Subo picks the chain per press, from the privacy mode. The DM is always tried first, so an anonymous project resolves to["dm", "web"]and any other project to["dm", "thread", "web"]. Sendnullto return to that. An empty array is rejected with a400rather than treated as a clear, as is a repeated surface. - It only applies to the Discord post answered in Discord. A
post with
answers_on: "web"and the web link answer on the web by definition; a chain set for them is stored, but nothing consults it. The reverse is refused:answers_on: "discord"with a chain that starts withwebis a400. -
An anonymous project should not use
thread: a thread is not anonymous to your team, since anyone with Manage Threads can read it.
Recipe: pull the responses
curl "https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects/$PROJECT_ID/responses?page=1&per_page=100" \
-H "X-API-Key: $SUBO_API_KEY" The shape you get back:
{
"data": [
{
"id": "...",
"project_id": "...",
"submitted_at": "2026-08-02T14:03:11Z",
"session_number": 1,
"user_id": "...",
"platform_id": "...",
"provider": "discord",
"answered_in": "dm",
"answers": [
{ "block_id": 1, "option_id": 2, "value": "A few times a week", "display": null },
{ "block_id": 2, "value": "More events in EU hours.", "display": null },
{ "block_id": 3, "option_id": 8769, "value": null, "display": "Minecraft" },
{ "block_id": 4, "value": "", "option_id": null, "skipped": true },
{
"block_id": 5,
"value": "[41]",
"display": null,
"files": [
{
"id": 41,
"name": "bug.png",
"category": "images",
"content_type": "image/png",
"bytes": 182044,
"url": "https://app.subo.gg/...",
"download_url": "https://api.subo.ai/v1/communities/.../projects/.../responses/files/41"
}
]
}
]
}
],
"pagination": { "page": 1, "per_page": 100, "total": 214, "has_more": true }
} per_pagedefaults to 20 and maxes out at 100. Page untilhas_moreis false.-
user_idis the Subo user id and the only globally unique key.platform_idis the account id inside its platform namespace, so it is only meaningful paired withprovider. Join onuser_id. -
provideris who admitted the respondent:discord,youtube,twitch,steam,patreon,google,web. A verified respondent carries the platform they verified with, and so does one who signed in on asigned_inlink (for examplegoogle). Sessions started from the Discord post arediscord, and unidentified sessions on ananyonelink areweb. -
displayis the people-readable form of an answer that holds a Discord mention. Answer options and question text can contain members, roles, games and dates in Discord's own format (<@id>member,<@&id>role,<@$id>game,<t:unix:style>date and time).valuekeeps that raw form;displayreads"Minecraft"or"2026-11-07 06:00 UTC"(dates are always UTC). For a picked option it is computed from the option's text. It isnullwhen there is nothing to make readable. -
skipped: truemarks a question the respondent skipped with the Skip button (itsvalueis"", itsoption_idnull). A block the respondent never reached has no answer at all. -
Answers to a
file_uploadblock carryfiles, one entry per file;filesisnullon every other block. Theirvalueis the stored list of file ids as a string, not text a person reads. Each file has two links that never expire:urlopens in a browser for someone signed in to Subo as an admin of the community or the project's creator (it takes no API key), anddownload_urlis for code holding an API key, below. -
One respondent can appear more than once when a project allows repeat
completions.
session_numberseparates those runs. -
answered_inis where the session happened:"thread", "dm", "web", ornull. It is a different axis fromprovider, which says who admitted the respondent, so ayoutuberespondent can answer on any of the three.nullmeans not recorded, not"thread". Every session collected before this field existed readsnull, so defaulting it to a surface will quietly miscount your history. Likeprovider, it survives on anonymous projects: where an interview happened is not respondent-identifying. - Anonymous projects come back redacted. When the project's
privacy_modeisanonymous,user_id,platform_idandsession_numberare alwaysnull, and theresponse.submittedwebhook nulls the same three. That matches what Subo's own surfaces do: the Responses tab hides identity and the XLSX export blanks the id, name, nickname and session columns. Filtering by respondent is refused rather than ignored, so?user_id=,?platform_id=and?session_number=return a400on an anonymous project. A caller who could filter and read back a non-empty page would have learned who answered. -
Redaction does not break grouping.
idstill identifies one submission and stays valid forGET .../responses/{responseId}, and the webhook always carriesresponse_idfor exactly that reason.provideris kept on anonymous projects too: the source someone came in through is not treated as identifying, the same rule the XLSX exports follow.
To download a file with an API key, request its download_url. It answers
with a 302 to a signed link that works for five minutes, so follow
redirects (curl -L, or "follow redirects" in Postman) and save the body,
or you save nothing. The signed link needs no key, and curl does not send your key
to it. ?thumb=1 returns an image's thumbnail.
curl -L -o evidence.png \
-H "X-API-Key: $SUBO_API_KEY" \
"https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects/$PROJECT_ID/responses/files/$FILE_ID"
A file the key cannot see answers 404, whether it belongs to another
project, was deleted, never finished uploading, or the key is a Creator key on a
project someone else created. Files answer 404 rather than
403 on purpose, so an id never reveals that a file exists. Reading and
downloading files costs no credits.
Polling this endpoint on a timer works, but webhooks are the better pipeline.
Recipe: summarize open-ended answers with AI
Free-text answers are the ones nobody has time to read. Trigger a
summarization pass over the open_text blocks:
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects/$PROJECT_ID/analysis" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "force": false }'
The job runs asynchronously, so the POST returns as soon as it is queued.
Read the result with a GET on the same path, which also returns
the aggregated stats and distributions for the closed questions:
curl "https://api.subo.ai/v1/communities/$COMMUNITY_ID/projects/$PROJECT_ID/analysis" \
-H "X-API-Key: $SUBO_API_KEY"
Set force: true to re-run a summary that already exists, for
instance after a wave of new responses. Analysis spends bot credits and
returns 402 payment_required on an empty balance. Rather than
polling for completion, subscribe to analysis.completed.
The result carries two counts that are easy to mix up.
total_sessions is the number of respondents, the same number
GET .../responses reports as pagination.total: use it
for "how many people answered." total_responses counts individual
answers across all blocks, so one person who answered six blocks counts six.
That second number is the one your plan's response limit counts.
Each block also carries skipped_count, the respondents who skipped an
optional question. response_count and every distribution percentage
leave skips out, so a skip never dilutes a chart.
Each distribution and ranking entry carries display and each block
carries prompt_display: the readable form of an option or a question
that holds a member, role, game or date mention, with dates in UTC. Both are
null when there is nothing to make readable; the raw text stays in
the original fields.
Recipe: subscribe to webhooks and verify them
Register an endpoint and the events you care about:
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/webhooks" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Responses to our warehouse",
"url": "https://example.com/hooks/subo",
"events": ["response.submitted", "analysis.completed", "project.closed"]
}'
The response contains signing_secret, shown once and never again.
Store it before you close the terminal. Every delivery then arrives with
these headers:
| Header | Value |
|---|---|
X-Subo-Event | The event type, for example response.submitted |
X-Subo-Delivery | A unique event id, useful for deduplication |
X-Subo-Signature | sha256=<hmac hex> over the raw body |
Verifying in Node:
import crypto from "node:crypto";
// req.body must be the RAW bytes, not a parsed and re-serialized object.
function verifySuboWebhook(rawBody, header, secret) {
const expected =
"sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(header || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
} Things worth knowing before you rely on this in production:
-
The
urlmust start withhttps://and resolve only to public addresses. Localhost, private networks and link-local addresses are refused when you save the webhook, and checked again before every delivery, so a hostname re-pointed at a private address later stops receiving. Redirects are not followed. To test against your own machine, put a public HTTPS tunnel in front of it. - Hash the raw request body. Re-serializing the JSON changes the bytes and every signature check will fail.
-
Compare in constant time. A plain
===leaks timing information. - Subo waits 10 seconds for your endpoint, then retries after 30s, 5m, 30m, 2h and 8h before abandoning the delivery. Return a 2xx fast and do the real work off the request path.
-
Deliveries are at-least-once. Deduplicate on
X-Subo-Delivery. -
response.submittedrequires a paid tier. The project lifecycle events are available to everyone. -
POST .../webhooks/{webhookId}/testfires a test delivery, andGET .../webhooks/{webhookId}/deliveriesshows attempt history with the status codes you returned. Use both before blaming the network.
Available events:
project.createdproject.updatedproject.openedproject.closedproject.status_changedproject.deletedresponse.submittedanalysis.completed
Recipe: clone a ready-made template
Subo ships curated templates: quizzes, prediction contests, feedback surveys. Cloning one is faster than writing a script and carries over the scoring, grading and reward blocks that make it work.
# Browse the catalog
curl "https://api.subo.ai/v1/templates" -H "X-API-Key: $SUBO_API_KEY"
# Clone one into your community
curl -X POST "https://api.subo.ai/v1/communities/$COMMUNITY_ID/templates/$TEMPLATE_ID/clone" \
-H "X-API-Key: $SUBO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "name": "Season 4 prediction contest" }' The clone is a deep copy: script, scoring buckets, grading, action blocks and calculated fields all come along. Anything bound to the source server, such as channels, roles and schedules, is stripped so you start clean. The new project arrives inactive, ready for an open call.
A machine-readable list of every public template, with slugs and clone links, lives at /templates.json.
Use Subo from an AI agent (MCP)
Everything on this page is also reachable through the Subo MCP server. MCP (Model Context Protocol) is the open standard AI apps use to connect to outside tools, so an AI assistant such as Claude Code can build, launch and read projects in your community without you writing a request.
Endpoint: https://api.subo.ai/mcp
Auth: OAuth 2.1 (sign in), or
Authorization: Bearer sbo_live_xxxxxxxxxxxxxxxxxxxxxxxx Sign in with OAuth (no key): in claude.ai or Claude Desktop, add a
custom connector with the endpoint above; in Claude Code, run this in a terminal,
restart, then type /mcp to authenticate. A community Admin signs in to
Subo with Discord, picks the community and an access level, and approves.
claude mcp add --transport http --scope user subo https://api.subo.ai/mcp Or use an API key, for apps that send a header. An Admin creates the key on the Account page under API Access, choosing Bot or agent. The confirmation panel shows the connection config with the key already in it:
claude mcp add --transport http --scope user subo https://api.subo.ai/mcp --header "Authorization: Bearer $SUBO_API_KEY" Each connection is bound to one community, so no operation takes a community id. Its 45 operations each carry one of four labels your AI app can read:
| Label | Meaning |
|---|---|
| Read-only | Reads data, changes nothing. |
| Normal change | Creates or edits something nobody sees yet, such as a draft project or its script. |
| Outward | Reaches real people: opening or closing a project, granting XP or accomplishments, firing a test webhook. |
| Destructive | Deletes data or invalidates a secret. |
The server also ships two prompts, which Claude Code shows as slash commands:
weekly_review reviews recent projects and their responses and
proposes the next one without changing anything, and
build_from_goal turns a goal into a validated project and stops
before opening it. Claude Code passes only the first word typed after a command,
so build_from_goal works best from an app that asks for its
goal as a field. Its resources include the script authoring guide
(subo://guide/authoring), the recipes and the
OpenAPI spec, so an agent can read them before it writes.
upload_image takes an image link and returns a Subo-hosted URL for
any image field, the same as the upload endpoint. An agent
cannot pass a file on, so the tool takes a link only.
An agent can add and edit file_upload blocks and sees each answer's
file list, but cannot download the files themselves: the download returns the raw
file, not data an assistant reads.
Three things are deliberately left out: creating, rotating or deleting API keys, changing a member’s access level, and connecting a new verified-audience source, which needs a person to sign in. Requests share the key’s rate limit with any other API use.
Step-by-step setup, scopes and key hygiene: How to connect your Discord community to an AI agent.
Reference tables
Block types
| Type | What it does |
|---|---|
single_punch | Pick one option. Also covers yes/no. |
multi_punch | Pick several options. |
open_text | Free text. The input for AI analysis. |
open_numeric | A number. |
rating | Rate on 2-10 points. Stars, numbers or an emoji set. |
opinion_scale | Agreement or satisfaction between two named ends. Label every point for a Likert item. |
nps | The standard 0-10 recommendation question. Range and anchors are locked. |
ranking | Put options in order, best first. rank_top_n asks for a partial ranking. |
file_upload | Members send files as their answer: attached in Discord or dropped in on the web. Rules in upload. |
content_block | Says something without asking anything. |
action_block | Grants XP, a role or an achievement mid-conversation. |
calculated_block | Computes a value from earlier answers. |
Scale family: ranges and defaults
| Type | Range | Default when omitted |
|---|---|---|
rating | 2 to 10 points, always starts at 1 | 1 to 5, stars |
opinion_scale | starts at 0 or 1, up to 11 points | 1 to 10, numbers |
nps | locked 0 to 10 | 0 to 10, not overridable |
ranking | 2 to 20 items | rank all items |
answer_style by block family
| Family | Accepted values | Rejected with 400 |
|---|---|---|
Choice (single_punch, multi_punch) | full_text, emoji_only, select_menu | — |
Scales (rating, opinion_scale, nps) | buttons (default), select_menu | full_text, emoji_only; nps also refuses select_menu |
ranking | full_text (default), emoji_only | select_menu, because a dropdown cannot express an order |
The predictable confusion: how a scale draws its points is
scale.icon, not an answer style. Stars, numbers and
emoji are icon values; answer_style only chooses
between a row of buttons and a dropdown. A dropdown is the better widget
from about six labelled points up, where a button row wraps.
Privacy modes
privacy_mode | Who can see who said what |
|---|---|
transparent | Answers are attributed openly. |
semi-private | Admins can see individual answers; other members cannot. |
anonymous | Nobody, including admins, can tie an answer to a member. |
Omit privacy_mode on create and the survey inherits the
privacy mode the community has configured as its default, the same one
the app applies. A community that has never changed that setting is on
anonymous. Set the field explicitly when
anonymity matters rather than relying on someone else's setting.
Rate limits
| Tier | Requests per minute |
|---|---|
| Free | 60 |
| Premium | 300 |
| VIP | 600 |
| Custom Bot | 1000 |
Limits are counted per key in a one-minute window. Every response carries
X-RateLimit-Limit, X-RateLimit-Remaining and
X-RateLimit-Reset; a 429 adds Retry-After.
See pricing for what else each tier includes.
Errors
| Status | Code | Usual cause |
|---|---|---|
| 400 | invalid_request | Bad body, unknown block type, or two mutually exclusive script sources. |
| 402 | payment_required | Out of bot credits for an AI call, or a feature above your tier. |
| 403 | forbidden | A Creator-scoped key reaching for a project it does not own. |
| 404 | not_found | Wrong community or project id for this key. |
| 422 | channel_required | Opening a project nobody can reach: no Discord post, no web link and no journey or campaign inviting to it. |
| 429 | rate_limit_exceeded | Over the tier limit. Wait Retry-After seconds. |
FAQ
- How do I authenticate with the Subo API?
- Send your key in the X-API-Key header on every request. Keys start with sbo_live_ and are created in the Subo web app under Community Account Tab, then API Keys. Each key is scoped to a single community and inherits your role, and it is shown only once.
- What is the Subo API base URL?
- https://api.subo.ai/v1. Non-breaking changes ship in place under /v1; breaking changes would ship under a new version prefix.
- Can an AI agent create a Discord survey with the Subo API?
- Yes. Pass an intent field, a plain-text description of what you want to learn, when creating a project and Subo generates the full multi-question script for you. The 201 response contains the generated blocks, so an agent can create a working survey in a single call.
- What are the Subo API rate limits?
- Limits are per API key and depend on the community tier: 60 requests per minute on Free, 300 on Premium, 600 on VIP and 1000 on Custom Bot. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and a 429 includes Retry-After.
- How do I create a rating or Likert scale question with the Subo API?
- Send a block with type rating or opinion_scale. The point range is the block’s min and max; the scale object sets the icon (numbers, stars or emoji) and the endpoint anchors. Per-point content goes in options, where option.value is the point number as a string and carries that point’s emoji or label. A label on every point is a Likert item. A plain star or number scale sends no options at all.
- Does the Subo API support NPS?
- Yes. Send { "type": "nps", "prompt": "..." } and nothing else. The range is locked to 0 to 10 and the standard anchors are rendered rather than stored, so every respondent reads them in their own language and no caller can edit them. Analysis returns the distribution and the average. Subo does not compute a promoter, passive and detractor rollup for you.
- Can I create a matrix or grid question with the Subo API?
- No, and it is a deliberate choice. A grid is a layout, not a question: every row of one is a single agreement or likelihood question. In Subo you send one opinion_scale block per statement with the same points on each, which takes about as long to write and reports as its own scale. Facing a grid all at once, respondents tend to run a straight line down one column; asked one at a time, they answer the question in front of them. A grid is also a wide table, which does not fit a phone or a chat client.
- How do I get survey responses out of Subo?
- Either poll GET /communities/{communityId}/projects/{projectId}/responses, which is paginated, or subscribe a webhook to the response.submitted event and receive each submission as it happens. Webhooks are the recommended path for pipelines.
- Does Subo have an MCP server?
- Yes, at https://api.subo.ai/mcp. AI apps that support MCP sign-in, such as claude.ai and Claude Code, connect with OAuth: a community Admin signs in with Discord, picks the community and an access level, and approves, with no key to copy. Other apps send Authorization: Bearer with an API key of type Bot or agent. It exposes 45 operations over the same API, bound to one community, and labels each one read-only, normal change, Outward (reaches real people) or Destructive (deletes), so an AI app knows which to confirm with you first. It cannot manage API keys, change access levels or connect a verified-audience source.
- How do I verify a Subo webhook signature?
- Compute an HMAC-SHA256 of the raw request body using the signing secret returned when you created the webhook, then compare it to the X-Subo-Signature header, which has the form sha256=<hex>. Always compare with a constant-time function and always hash the raw bytes, not a re-serialized object.
Where to go next
- Full endpoint reference for every field and response shape.
- OpenAPI 3.1 spec to generate a client or feed an agent.
- llms.txt if you are pointing an AI agent at Subo.
- Tutorials for the no-code path through the same features.
- Support server when something behaves in a way this page did not predict.
START A CONVERSATION WITH YOUR COMMUNITY.
No credit card. No setup hassle. Just jump in and play around with few limitations. Do more with paid plans when you're ready.