# Subo

Subo is a survey and poll app trusted by 15,000+ Discord communities. It lets community managers, developers, and AI agents create conversational surveys and polls, collect responses, and analyze results — all inside Discord or on the web.

## Subo API

The Subo Public REST API (v1) gives developers and AI agents programmatic access to create, manage, and analyze conversational surveys and polls inside Discord communities and on the web.

AI agents can use this API to:
- Automatically generate full survey scripts from natural language intents or specific scripts
- Create, open, and manage survey projects
- Retrieve responses and trigger AI analysis
- React to real-time events via webhooks (project opened/closed, response submitted, analysis completed)

## Docs

- [API Quickstart & Recipes](https://subo.gg/api): Static, crawlable quickstart plus end-to-end recipes (AI script generation, opening a project, pulling responses, AI analysis, webhook signature verification) with copy-paste curl. Start here.
- [API Documentation](https://api.subo.ai/docs): Interactive Scalar UI with full endpoint reference
- [OpenAPI Spec](https://api.subo.ai/v1/openapi.json): Raw OpenAPI 3.1.0 JSON spec — machine-readable
- [Get an API Key](https://app.subo.gg/app/account): Generate keys in the Community account tab, under API Access
- [Subo Homepage](https://subo.gg/): Product overview and feature list
- [Pricing](https://subo.gg/pricing): Plans (FREE, PREMIUM, VIP, CUSTOM) and rate limits per tier
- [Blog](https://subo.gg/blog): News and updates

## Templates

Subo ships ready-made, cloneable survey, poll, and quiz templates. Each has a public landing page and can be cloned into a community from the web app, or built programmatically via the API.

- [Template gallery](https://subo.gg/templates): Browse all templates by goal (Engage, Understand, Get things done).
- [Template catalog (JSON)](https://subo.gg/templates.json): Machine-readable list of every template with slugs, showcased features, and clone links. This is the canonical, always-current list.

Example templates:
- [Event Prediction Contest](https://subo.gg/templates/event-prediction-contest): Turn any match, tournament, or awards night into a prediction game with scoring, grading, and score-based XP rewards.
- [Lore Trivia Quiz](https://subo.gg/templates/lore-trivia-quiz): Quiz a community on any body of knowledge with automatic grading, per-answer feedback, and an achievement for everyone who passes.

## What the API Does

Authentication: `X-API-Key` request header (scoped to a community). Rate limits: 60–1,000 req/min depending on tier.
Idempotency: Send `Idempotency-Key: <UUIDv4>` header on all write operations

Key resources:
- **Projects** — Create, manage, open, close, clone surveys and polls
- **Script & Blocks** — Build survey scripts (single choice, multiple choice, open text, numeric, content, action and calculated blocks)
- **Responses** — Retrieve paginated respondent answers
- **Analysis** — Aggregated stats and AI summarization of open-ended answers
- **Communities** — Manage community settings such as accomplishments, XP and default survey settings
- **Members** — View all community members and manage their XP, access levels and accomplishments
- **Webhooks** — Real-time event subscriptions (project lifecycle, response submitted, analysis completed)
- **AI Generation** — Auto-generate a full survey script from a plain-text intent description
- **API Keys** — Create and revoke scoped keys

## Most Useful Endpoints for AI Agents

All paths below are relative to `https://api.subo.ai/v1`. Almost every endpoint is
nested under a community: resolve `{communityId}` first with `GET /communities`.

1. **Create Project (with AI script generation)**
   - `POST /communities/{communityId}/projects`
   - Use `intent` field for natural language → full script (e.g. "Measure member satisfaction after the last event")
   - `type` is `convo` (multi-question survey) or `poll`; `max_blocks` defaults to 5, max 20
   - Alternative: Provide full `script.blocks` manually (mutually exclusive with `intent`)
   - Returns project + generated script; the project starts `inactive`

2. **Replace / Update Script**
   - `PUT /communities/{communityId}/projects/{projectId}/script`
   - Replace entire script when project is inactive
   - Per-block edits: `POST|PUT|DELETE .../script/blocks[/{blockId}]`

3. **Open Project**
   - `POST /communities/{communityId}/projects/{projectId}/open`
   - Makes the survey live. `delivery.audience` picks the channel:
     `private`+`discord` (answer in Discord), `private`+`web` (members-only link),
     `open_web`+`web` (open link, no Discord account needed)
   - Close early with `POST .../projects/{projectId}/close`

4. **List or Get Responses**
   - `GET /communities/{communityId}/projects/{projectId}/responses` (paginated; `per_page` max 100)
   - `GET /communities/{communityId}/projects/{projectId}/responses/{responseId}`
   - Join on `user_id` (globally unique); `platform_id` is only unique within its `provider` namespace
   - `privacy_mode` does not redact this endpoint. `user_id`, `platform_id` and
     `session_number` are returned for anonymous projects too (the app's own Responses
     tab and XLSX export mask them; the API does not), as is the `response.submitted`
     webhook payload. Drop those fields at your ingestion boundary if the project
     promised anonymity.

5. **Trigger AI Analysis**
   - `POST /communities/{communityId}/projects/{projectId}/analysis` (async; `{"force": true}` re-runs)
   - `GET` the same path for summaries plus aggregated stats and distributions

6. **Webhooks** (Highly recommended for agents)
   - `POST /communities/{communityId}/webhooks` with `{url, name, events[]}`
   - Events: `project.created`, `project.updated`, `project.opened`, `project.closed`,
     `project.status_changed`, `project.deleted`, `response.submitted`, `analysis.completed`
   - `signing_secret` is returned once. Deliveries carry `X-Subo-Event`, `X-Subo-Delivery`
     and `X-Subo-Signature: sha256=<hmac hex>` (HMAC-SHA256 over the raw body)
   - Retries at 30s, 5m, 30m, 2h, 8h; deliveries are at-least-once, so dedupe on `X-Subo-Delivery`

7. **Clone a Template**
   - `GET /templates`, then `POST /communities/{communityId}/templates/{templateId}/clone`
   - Deep clone (script, scoring, grading, action blocks); source-server bindings stripped

## Recipes (survey designs, on-domain)

End-to-end walkthroughs of real survey designs: the script, the action blocks, the
scoring, and the logic that ties them together. Served as plain markdown, so an agent can
fetch one and follow it directly. These are survey-*design* recipes; for API *mechanics*
(auth, pagination, webhook signatures) use https://subo.gg/api.

Canonical home: https://subo.gg/recipes (HTML, with FAQ and template cross-links).
The same ten are also fetchable as raw markdown from the API host, which is convenient
for agents but NOT canonical:
- `GET https://api.subo.ai/v1/recipes` — JSON index (slug, title, summary, url)
- `GET https://api.subo.ai/v1/recipes/{slug}` — full markdown for one recipe

- [Welcome quiz](https://subo.gg/recipes/welcome-quiz): Onboard new members by recording region, language and notification preferences; choices fire achievements linked to Discord roles.
- [Volunteer / moderator funnel](https://subo.gg/recipes/volunteer-moderator-funnel): Screening funnel where one decisive question gates mutually-exclusive Mod Trial vs Waitlist role grants.
- [Event RSVP with attendance streaks](https://subo.gg/recipes/event-rsvp-streak): RSVP funnel using session-scoped firing plus XP-threshold achievements to produce streak rewards without per-event tagging.
- [Playtester selection](https://subo.gg/recipes/playtester-selection): Recruit qualified playtesters via availability gating; qualifiers get a durable Beta Tester achievement and role.
- [Hogwarts house sorting quiz](https://subo.gg/recipes/hogwarts-house-sorting-quiz): Personality-style sorting via argmax over hidden buckets, assigning one outcome role.
- [Member segmentation](https://subo.gg/recipes/member-segmentation): Segment a community into personas using the same hidden-bucket argmax pattern.
- [Study quiz](https://subo.gg/recipes/study-quiz): Graded quiz using correct_answer_index with when_correct / when_incorrect feedback branches.
- [World capitals quiz](https://subo.gg/recipes/world-capitals-quiz): Knowledge quiz with per-answer grading and scored leaderboard results.
- [Prediction poll](https://subo.gg/recipes/prediction-poll): Prediction contest where option weights price risk, so unlikely correct calls score higher.
- [Pre/post assessment](https://subo.gg/recipes/pre-post-assessment): Measure change over time with twin projects capped at one completion per user each.

## Key Features Agents Love
- **AI Script Generation**: Turn a plain-text goal into a complete multi-block survey script in one call.
- **Real-time Webhooks**: Get notified instantly when new responses arrive or analysis is ready.
- **Rich Script System**: Supports single/multiple choice, open text, numeric, conditional logic (structured `show_when` / `hide_when`, compiled to a precondition), and content, action and calculated blocks. The block-type list at the bottom of this file is the complete set the API accepts; a Discord-only question type such as yes/no is sent as `single_punch`.
- **Analysis**: Built-in AI summarization of qualitative answers.

## Best Practices for Agents
- Always include `Idempotency-Key` on POST/PUT/DELETE operations.
- Use webhooks instead of polling for new responses and analysis results.
- Start with the `intent` field when creating projects — it’s the fastest way to generate high-quality surveys.
- Handle `402` errors gracefully (insufficient bot credits for AI features).

Base URL: https://api.subo.ai
Version: /v1/ (non-breaking changes in-place; breaking changes under /v2/)
Idempotency: Pass `Idempotency-Key` (UUID v4) header on write operations.
Block types: `single_punch`, `multi_punch`, `open_text`, `open_numeric`, `content_block`, `action_block`, `calculated_block`.
Privacy modes: `transparent`, `semi-private`, `anonymous` (omitting `privacy_mode` inherits the community's configured default, `anonymous` for a community that never changed it — set it explicitly when anonymity matters).
Errors: `400 invalid_request`, `402 payment_required` (out of bot credits / tier-gated), `403 forbidden`, `404 not_found`, `429 rate_limit_exceeded` (honor `Retry-After`).

Worked examples with copy-paste curl for all of the above: https://subo.gg/api
Survey-design recipes (ten worked walkthroughs): https://subo.gg/recipes