REST API

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.

Base URL https://api.subo.ai/v1 · OpenAPI 3.1 spec at /v1/openapi.json

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:

  • type is convo for a multi-question survey or poll for a single question.
  • quality is quick or deep. 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_count is optional: leave it out and the model picks what the goal needs, capped at 20 and at your plan's limit. max_blocks is still accepted as a deprecated alias.
  • facts takes 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 explicit script and source_project_id are mutually exclusive. Send exactly one.
  • AI generation spends bot credits. With an empty balance the call returns 402 payment_required rather than a partial survey.
  • language takes 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_language sets the language of the draft's notes; when omitted it is inferred from the intent and the response's notices says so.
  • The response's draft object carries author_notes (what to check before opening), the dropped and flagged blocks, the model and credits_used.
  • Want the plan step the dashboard shows (outline, up to three questions, facts needed)? POST /communities/{communityId}/projects/generate/plan returns it; send its plan, your answers and its session_id with 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-Key is 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_large with max_bytes and, when a bigger plan exists, upgrade: {plan, max_bytes}.
  • A url must 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_limited with Retry-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 unavailable means uploads are switched off, and 502 upstream_error that 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:

typeFieldsWho 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_on on the Discord post. discord: members answer in Discord (thread or DM, see answer_surfaces below). 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 from GET /communities/{communityId}/sources (see Audience Sources below). Turning the link on without who means verified with the community’s Discord server.
  • who: "signed_in" names everyone, checks nothing. The respondent signs in with one of sign_in_with (discord, twitch, google, steam) and answers as themselves; no server, follow or role is required, and nothing needs connecting first. google is a Google account, not a YouTube channel. A platform Subo cannot offer yet is a 400 that lists the available ones. A new signed_in link without sign_in_with offers discord. 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, set privacy_mode: "anonymous", which covers the Discord post too.
  • Required roles gate every Discord check. required_role_ids (any-of, set on discord_post) is checked where a member presses the post and where someone verifies with Discord on a verified web link. It does not apply on an anyone or signed_in link, 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: share delivery.share_url.
  • delivery.share_url is the web link while web_link is on, and null while it is off.
  • delivery.audience is deprecated. Its participation / response_channel pair still works, and sending back the pair you read changes nothing, but it cannot describe a post answered in Discord beside a web link. Use entry_points, and never send both: that is a 400.

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"]
  }
}
SurfaceWhere 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.

  • null is 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"]. Send null to return to that. An empty array is rejected with a 400 rather 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 with web is a 400.
  • 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_page defaults to 20 and maxes out at 100. Page until has_more is false.
  • user_id is the Subo user id and the only globally unique key. platform_id is the account id inside its platform namespace, so it is only meaningful paired with provider. Join on user_id.
  • provider is 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 a signed_in link (for example google). Sessions started from the Discord post are discord, and unidentified sessions on an anyone link are web.
  • display is 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). value keeps that raw form; display reads "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 is null when there is nothing to make readable.
  • skipped: true marks a question the respondent skipped with the Skip button (its value is "", its option_id null). A block the respondent never reached has no answer at all.
  • Answers to a file_upload block carry files, one entry per file; files is null on every other block. Their value is the stored list of file ids as a string, not text a person reads. Each file has two links that never expire: url opens 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), and download_url is for code holding an API key, below.
  • One respondent can appear more than once when a project allows repeat completions. session_number separates those runs.
  • answered_in is where the session happened: "thread", "dm", "web", or null. It is a different axis from provider, which says who admitted the respondent, so a youtube respondent can answer on any of the three. null means not recorded, not "thread". Every session collected before this field existed reads null, so defaulting it to a surface will quietly miscount your history. Like provider, it survives on anonymous projects: where an interview happened is not respondent-identifying.
  • Anonymous projects come back redacted. When the project's privacy_mode is anonymous, user_id, platform_id and session_number are always null, and the response.submitted webhook 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 a 400 on 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. id still identifies one submission and stays valid for GET .../responses/{responseId}, and the webhook always carries response_id for exactly that reason. provider is 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:

HeaderValue
X-Subo-EventThe event type, for example response.submitted
X-Subo-DeliveryA unique event id, useful for deduplication
X-Subo-Signaturesha256=<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 url must start with https:// 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.submitted requires a paid tier. The project lifecycle events are available to everyone.
  • POST .../webhooks/{webhookId}/test fires a test delivery, and GET .../webhooks/{webhookId}/deliveries shows attempt history with the status codes you returned. Use both before blaming the network.

Available events:

  • project.created
  • project.updated
  • project.opened
  • project.closed
  • project.status_changed
  • project.deleted
  • response.submitted
  • analysis.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:

LabelMeaning
Read-onlyReads data, changes nothing.
Normal changeCreates or edits something nobody sees yet, such as a draft project or its script.
OutwardReaches real people: opening or closing a project, granting XP or accomplishments, firing a test webhook.
DestructiveDeletes 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

TypeWhat it does
single_punchPick one option. Also covers yes/no.
multi_punchPick several options.
open_textFree text. The input for AI analysis.
open_numericA number.
ratingRate on 2-10 points. Stars, numbers or an emoji set.
opinion_scaleAgreement or satisfaction between two named ends. Label every point for a Likert item.
npsThe standard 0-10 recommendation question. Range and anchors are locked.
rankingPut options in order, best first. rank_top_n asks for a partial ranking.
file_uploadMembers send files as their answer: attached in Discord or dropped in on the web. Rules in upload.
content_blockSays something without asking anything.
action_blockGrants XP, a role or an achievement mid-conversation.
calculated_blockComputes a value from earlier answers.

Scale family: ranges and defaults

TypeRangeDefault when omitted
rating2 to 10 points, always starts at 11 to 5, stars
opinion_scalestarts at 0 or 1, up to 11 points1 to 10, numbers
npslocked 0 to 100 to 10, not overridable
ranking2 to 20 itemsrank all items

answer_style by block family

FamilyAccepted valuesRejected 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_modeWho can see who said what
transparentAnswers are attributed openly.
semi-privateAdmins can see individual answers; other members cannot.
anonymousNobody, 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

TierRequests per minute
Free60
Premium300
VIP600
Custom Bot1000

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

StatusCodeUsual cause
400invalid_requestBad body, unknown block type, or two mutually exclusive script sources.
402payment_requiredOut of bot credits for an AI call, or a feature above your tier.
403forbiddenA Creator-scoped key reaching for a project it does not own.
404not_foundWrong community or project id for this key.
422channel_requiredOpening a project nobody can reach: no Discord post, no web link and no journey or campaign inviting to it.
429rate_limit_exceededOver 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

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.