Projects

Create project

Create a new project. Starts inactive. Script input options (mutually exclusive):

  • script.blocks — provide an explicit block list; written immediately, no credits consumed
  • intent — natural-language description; AI drafts the script (every block type, scoring, show_when) and writes it through the same validation as PUT /script; consumes bot credits; returns 402 if the balance is below the chosen quality's floor. Takes the same draft inputs as POST /projects/generate (quality, question_count, language, facts, and plan + answers + session_id from POST /projects/generate/plan). The community's default welcome block is not added: the draft brings its own intro when it wants one.
  • source_project_id — fork script from an existing project
  • (none) — project is created with an empty script

When script or intent is provided the response includes a script.blocks field; with intent it also includes draft (author notes, dropped blocks, model, credits).

post/v1/communities/{communityId}/projects

Request

  • Base URL: https://api.subo.ai
  • URL: https://api.subo.ai/v1/communities/{communityId}/projects
  • Auth: API key in header X-API-Key

Path parameters

communityIdstring required

Community ID (Discord guild snowflake, serialized as string)

Request body

namestring required
type'convo' | 'poll' required
source_project_idstring nullable

Fork script from this project ID

max_completes_per_userinteger

Maximum times a single participant can complete this project

privacy_mode'transparent' | 'semi-private' | 'anonymous'

Controls response visibility and identity disclosure. If omitted, the community's default privacy mode is used (GET /v1/communities/{communityId} → defaults.privacy_mode; anonymous for communities that never changed it).

  • transparent — All community members can see exactly who answered what for every question.
  • semi-private — Only the project creator and community admins can view individual responses (who answered what). The rest of the community sees aggregated results only if the creator chooses to share them.
  • anonymous — Respondent identity is hidden from everyone, including the creator and admins. Data is pseudo-anonymous: answers are recorded but not linked to a user ID or display name, unless a respondent volunteers that information in an open-text answer. Caveat: XP and achievements can still be granted in anonymous projects, so participation is not entirely hidden — particularly relevant in small communities.
scoring_enabledboolean nullable

Enable quiz/scoring mode. When true, question blocks may carry correct_answer_index, when_correct, when_incorrect, and per-option score_values. Set this before writing a script that uses score variables — without it, score_values weights are silently ignored and [score]/[correct_answers] variables render as literal [brackets]. Do not also set rewards.use_xp: true when using an in-survey give_xp action block with a source_key — that combination awards XP twice.

intentstring

Natural-language description of the survey goal. Mutually exclusive with script. AI drafts the script and writes it; the response includes script.blocks and draft. The draft inputs below are read only when intent is set.

quality'quick' | 'deep'

Draft quality. quick is a fast, low-cost model; deep is a stronger model that costs far more credits (typically ~24,000-48,000 versus ~700) and needs a balance of at least its floor to start. Defaults to deep on any paid plan, quick otherwise.

question_countinteger

How many questions to draft (intro, content and action blocks not counted). Capped by the plan's limit. Omit to let the model choose what the goal needs.

max_blocksinteger

Deprecated alias of question_count.

languagestring

Language respondents will read: any language's name (French, Tagalog) or a locale code (fr, pt-BR, ja). Defaults to a language the intent names ("a poll in Tagalog"), else the community's. Only a value that is not a language name or code is a 400.

admin_languagestring

Language the plan and author_notes are written in for you (the author): any language's name or a locale code. It never sets the project's language. When omitted it is inferred from the intent, and the response's notices say so.

factsstring

Facts the model cannot know and must use as given: dates, line-ups, results, odds. The model's knowledge has a cutoff, so pass anything current here.

answersobject

Your answers to the plan's questions: plan question id -> answer text.

session_idstring

The session_id from POST /projects/generate/plan, so the plan and the draft are recorded as one exchange. Optional.

Example request

{
  "name": "Customer Satisfaction Survey",
  "intent": "Measure how satisfied members are with last week's event",
  "language": "fr",
  "admin_language": "en"
}

Response

Created. Response includes data.script.blocks when script or intent was provided. If the AI draft failed after the project was created, data.script is null, data.script_error is "ai_failure" and data.script_error_detail says why and what was charged. The project still exists, empty; add a script with PUT /script or retry with POST /projects/generate.

Changes

No recorded changes to this operation across all 1 revision of this API.