---
title: "Plan an AI draft"
method: POST
path: "/v1/communities/{communityId}/projects/generate/plan"
tags: ["Script"]
---

# Plan an AI draft

`POST /v1/communities/{communityId}/projects/generate/plan`

## Request

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

Optional first step of an AI draft. Returns what the model understood (`outline`), up to 3 questions for the author with suggested answers, and the facts it needs. Agents that already send a complete intent skip it. To use it, pass the returned `plan`, your `answers` (by question `id`) and `session_id` to `POST /projects/generate` or `POST /projects` with `intent`. Always runs on the Quick model (~150-350 credits). Writes nothing.

## Path parameters

- `communityId` string, required

## Request body

- object
  - `intent` string, required: The goal of the convo in plain language
  - `question_count` integer: 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.
  - `language` string: 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_language` string: 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.

## Response `200`

The plan, the qualities you can afford, and the session to continue

- object
  - `data` object
    - `session_id` string
    - `plan` DraftPlan: What the AI understood and what it would like to know before drafting.
      - `kind` 'survey' | 'poll'
      - `title` string
      - `question_count` integer, nullable
      - `outline` string[]: One line per planned block.
      - `questions` object[]: Questions for the author. Answer them in `answers` by `id`; unanswered ones are left to the model. A question with `id` `language` comes when the intent is written in a language that is neither yours (`admin_language`) nor the project's: its 4 suggestions, in order, keep the project's language, write the project in the intent's language, write only `author_notes` in it, or both. Answer with the suggestion's text.
        - `id` string
        - `question` string
        - `suggestions` string[]
      - `facts_needed` string: Facts the draft needs from you (pass them in `facts`); empty when none.
      - `notes` string
      - `request_language` string: The language the intent is written in, as the model read it.
      - `named_language` string: The language respondents should read when the intent names one ("a poll in Tagalog"); empty otherwise.
    - `language` string: The language the draft will use unless you pass another: the one you passed, else one the intent names, else the community's.
    - `admin_language` string, nullable: The language the plan is written in for you.
    - `notices` string[]: Non-blocking notes in English. When `admin_language` was not given, one says which language it was inferred as and how to choose another.
    - `quality` 'quick' | 'deep': The community's default quality.
    - `qualities` object: Per quality: `estimate`, the credits a draft of this plan's size should cost (it grows with the outline's length), the `floor` balance needed to start, and whether the balance is `affordable`.
    - `credits_used` integer

## Other responses

- `400`: Bad request
- `401`: Invalid or missing API key
- `402`: Insufficient bot credits
- `429`: Rate limit exceeded — wait `retry_after` seconds before retrying. The same value appears in the `Retry-After` header.
- `500`: The model call failed (nothing charged)

---

[API](https://skmtc.dev/subo/apis/subo-api.md) · [All operations](https://skmtc.dev/subo/apis/subo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/subo/apis/subo-api/revisions/12eab2ae4505?raw)