> ## Documentation Index > Fetch the complete documentation index at: https://developers.huechat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Generate a validated form preview through Agent AI > Requires ai_agents:write AND forms:write; browser administrator. Prompt 1–4,000 characters, native provider budget, max 20 questions.10 attempts/account/UTC month; failures count. UUID exact successful retry replays, pending/different request 409; confirmed failed attempt 502. Does not save/publish/send.502 and 429 include usage. Generated drafts cannot configure private mappings, external resources or unsupported operational services. Selected agent ai_settings.forms_enabled must be true; otherwise403. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/accounts/{accountId}/ai-agents/{agentId}/forms/generate openapi: 3.0.3 info: contact: name: HueChat support email: support@huechat.ai url: https://huechat.ai/contact description: >- Account-scoped REST API for HueChat: conversations, messages, contacts, Customer CDP, Sales CRM, forms, appointments, inboxes, teams, agents, AI agents and knowledge, WhatsApp templates and broadcasts, workflows and chat menus. Authenticate with account-scoped API keys; every route is scoped to your own account. license: name: Proprietary url: https://huechat.ai/terms termsOfService: https://huechat.ai/terms title: HueChat API version: 2.0.0 servers: - url: https://app.huechat.ai description: Production security: - bearerAuth: [] tags: - name: Agents description: The human agents on your account and their availability. - name: AI Agents description: >- Assistants you build to answer customers on their own: persona, language, guardrails, tools and a knowledge base, published to inboxes, replying in Arabic or English until they hand off to a human. Create, publish, test, monitor quality and roll back versions. - name: Broadcasts description: >- Send a WhatsApp template to a list of contacts from a CSV or saved audience, with scheduling, pause and resume, and delivery reports. - name: Chat Menus description: >- Numbered or button-driven menus a customer sees at the start of a conversation. - name: Contacts description: >- The people your team talks to: phone, email, name, custom attributes, labels and notes. One contact can have conversations on several channels. - name: Conversations description: >- A conversation is one thread between a contact and your team on one channel, with status, assignee, team, labels, priority and custom attributes. List, filter, search, assign, resolve and annotate them. - name: Forms description: >- Form management, assets, delivery, respondent sessions, submissions, scheduling, reports and AI-assisted authoring in one group. - name: Inboxes description: >- Connected channels: a WhatsApp Business number, an Instagram or Messenger page, an email address or a website live-chat widget. Inboxes decide where a conversation comes from and who can see it. - name: Knowledge description: >- Documents, web pages and text that ground an AI agent's answers. Upload, point at a URL or paste text; HueChat indexes it and the agent cites it. - name: Messages description: >- Everything said inside a conversation: text, attachments, WhatsApp templates and interactive replies. Sending through the API delivers on the conversation's channel and shows in the inbox like any agent reply. - name: Sales CRM description: >- The full tenant-scoped Sales workspace: Leads, Companies, Deals, tasks, products, price books, quotes, payments, forecasts, reports and settings. - name: Teams description: Groups of agents used for assignment and reporting. - name: Templates description: >- Pre-approved WhatsApp message formats required by Meta for business-initiated messages. Create, sync from Meta, AI-generate, test-send and read analytics. - name: Workflows description: >- Automation flows built from triggers and steps: route, tag, reply, wait, hand off. Create, publish, version and toggle. paths: /api/v2/accounts/{accountId}/ai-agents/{agentId}/forms/generate: parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/agentId' post: tags: - Forms summary: Generate a validated form preview through Agent AI description: >- Requires ai_agents:write AND forms:write; browser administrator. Prompt 1–4,000 characters, native provider budget, max 20 questions.10 attempts/account/UTC month; failures count. UUID exact successful retry replays, pending/different request 409; confirmed failed attempt 502. Does not save/publish/send.502 and 429 include usage. Generated drafts cannot configure private mappings, external resources or unsupported operational services. Selected agent ai_settings.forms_enabled must be true; otherwise403. operationId: postApiV2AccountsAccountidAiAgentsAgentidFormsGenerate requestBody: required: true content: application/json: schema: type: object properties: prompt: type: string minLength: 1 maxLength: 4000 language: $ref: '#/components/schemas/Language' idempotency_key: type: string format: uuid required: - prompt - idempotency_key additionalProperties: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GeneratedPreview' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PlanDisabled' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/ProviderError' '503': $ref: '#/components/responses/Unavailable' security: - bearerAuth: [] components: parameters: accountId: name: accountId in: path required: true schema: type: integer minimum: 1 agentId: name: agentId in: path required: true schema: type: string format: uuid schemas: Language: type: string enum: - en - ar - es - fr - hi - ja - pt - zh_CN GeneratedPreview: type: object properties: generation_id: type: string format: uuid title: type: string definition: $ref: '#/components/schemas/Definition' usage: $ref: '#/components/schemas/GenerationUsage' Definition: type: object required: - language - questions properties: language: $ref: '#/components/schemas/Language' branding: $ref: '#/components/schemas/Branding' questions: type: array maxItems: 100 items: $ref: '#/components/schemas/Question' cdp_mapping: type: array items: $ref: '#/components/schemas/CDPMapping' advancedLogic: $ref: '#/components/schemas/AdvancedLogic' logic: type: object additionalProperties: true description: type: string maxLength: 4000 domain: type: string maxLength: 120 mode: type: string enum: - universal - lead - quiz - match accent: type: string pattern: ^#[0-9a-fA-F]{6}$ thankYou: type: string maxLength: 4000 share: $ref: '#/components/schemas/ShareSettings' controls: type: object properties: responseCap: type: integer minimum: 0 maximum: 10000000 default: 0 translations: $ref: '#/components/schemas/Translations' create_contacts: type: boolean default: false description: >- With explicit profile_consent and valid mapped identifiers, may create a new unverified lead; never claims an existing profile by typed phone/email. description: >- Owner editable definition, maximum serialized size 256 KiB. PublicDefinition strips notes and private AI configuration. GenerationUsage: type: object properties: used: type: integer limit: type: integer enum: - 10 remaining: type: integer resets_at: type: string format: date-time required: - used - limit - remaining - resets_at Error: type: object properties: error: type: string Branding: type: object properties: name: type: string maxLength: 120 logo_url: type: string description: HTTPS URL or safe root-relative asset path logo_alt: type: string maxLength: 160 show_logo: type: boolean show_name: type: boolean Question: type: object required: - id - type - title properties: id: type: string pattern: ^[A-Za-z0-9_-]{1,80}$ type: type: string enum: - welcome - statement - group - partial_submit - end - redirect - contact_info - email - phone - address - website - single_choice - multiple_choice - dropdown - picture_choice - yes_no - legal - checkbox - rating - nps - csat - opinion_scale - ranking - matrix - short_text - long_text - video_audio - ai_clarify - ai_faq - number - date - signature - payment - file - scheduler title: type: string maxLength: 300 required: type: boolean options: type: array maxItems: 100 items: type: string rows: type: array maxItems: 50 items: type: string columns: type: array maxItems: 50 items: type: string min: type: number max: type: number score: type: object additionalProperties: type: number description: type: string maxLength: 4000 placeholder: type: string maxLength: 300 titleDelta: $ref: '#/components/schemas/RichDelta' descriptionDelta: $ref: '#/components/schemas/RichDelta' images: type: array maxItems: 100 items: type: string mediaUrl: type: string mediaKind: type: string enum: - image - video presentation: type: string enum: - text - video randomize: type: boolean currency: type: string pattern: ^[A-Z]{3}$ amount: type: number minimum: 0 maximum: 10000000 redirectUrl: type: string format: uri notes: type: array items: type: string maxLength: 500 maxItems: 30 schedule: $ref: '#/components/schemas/ScheduleConfig' ai: $ref: '#/components/schemas/AIQuestionConfig' description: >- 35 recognized stored kinds. Only payment is draft-only. signature is typed-name; scheduler/file/video_audio/AI answers require native server receipts. Required display-only screens are invalid. Notes and private AI config are removed in public definitions. CDPMapping: type: object required: - question_id - target - fill_policy properties: question_id: type: string subfield: type: string target: type: string enum: - name - email - phone_number - country_code - website - age fill_policy: type: string enum: - fill_empty prefill_from_cdp: type: boolean AdvancedLogic: type: object properties: allowedUrlParams: type: array items: type: string pattern: ^[A-Za-z][A-Za-z0-9_-]{0,39}$ maxItems: 20 variables: type: array items: type: object properties: name: type: string initial: type: number minimum: -1000000000000 maximum: 1000000000000 required: - name - initial maxItems: 50 startRules: type: array items: $ref: '#/components/schemas/LogicRoute' maxItems: 100 questionRules: type: array items: type: object properties: questionId: type: string hideWhen: $ref: '#/components/schemas/LogicGroup' branches: type: array items: $ref: '#/components/schemas/LogicRoute' maxItems: 30 fallback: $ref: '#/components/schemas/LogicDestination' calculations: type: array items: $ref: '#/components/schemas/LogicCalculation' maxItems: 30 required: - questionId maxItems: 100 description: >- Server validates references and recalculates path/variables. Reserved invite/rev/token/code URL names and unsafe variable names are rejected. ShareSettings: type: object properties: expires_at: type: string format: date-time single_use: type: boolean default: true title: type: string maxLength: 160 description: type: string maxLength: 500 image_url: type: string description: >- Published snapshot settings. Existing invitation versions remain pinned; share_mode access is a live form-level control. Translations: type: object properties: schemaVersion: type: integer enum: - 1 updatedAt: type: string languages: type: object maxProperties: 8 additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/TranslatedQuestion' description: Keys are constrained to the Language enumeration. required: - schemaVersion - languages description: >- Key by supported locale then question ID; __form__ holds thankYou. Translated option/row/column arrays retain canonical length/order. RichDelta: type: object properties: ops: type: array items: type: object properties: insert: type: string attributes: type: object properties: bold: type: boolean italic: type: boolean underline: type: boolean additionalProperties: false required: - insert additionalProperties: false maxItems: 300 required: - ops description: Text-only Quill delta; no HTML, links or embedded objects. additionalProperties: false ScheduleConfig: type: object properties: service_id: type: string format: uuid resource_id: type: string format: uuid required: - service_id AIQuestionConfig: type: object properties: agent_id: type: string format: uuid instructions: type: string maxLength: 2000 knowledge: type: string maxLength: 8000 max_turns: type: integer minimum: 1 maximum: 3 required: - agent_id - max_turns description: >- Owner-only configuration. FAQ requires non-empty approved knowledge. Public definitions remove all fields except max_turns. LogicRoute: type: object properties: when: $ref: '#/components/schemas/LogicGroup' destination: $ref: '#/components/schemas/LogicDestination' required: - when - destination LogicGroup: type: object properties: mode: type: string enum: - all - any conditions: type: array items: $ref: '#/components/schemas/LogicCondition' maxItems: 20 LogicDestination: type: object properties: kind: type: string enum: - next - end - question questionId: type: string required: - kind LogicCalculation: type: object properties: when: $ref: '#/components/schemas/LogicGroup' operation: type: string enum: - set - add - subtract - multiply - divide target: type: string operand: type: object properties: kind: type: string enum: - constant - answer - variable value: type: string required: - kind - value required: - operation - target - operand TranslatedQuestion: type: object properties: title: type: string maxLength: 300 description: type: string maxLength: 4000 placeholder: type: string maxLength: 300 options: type: array items: type: string maxLength: 300 maxItems: 100 rows: type: array items: type: string maxLength: 300 maxItems: 50 columns: type: array items: type: string maxLength: 300 maxItems: 50 thankYou: type: string maxLength: 4000 LogicCondition: type: object properties: source: type: object properties: kind: type: string enum: - answer - url - variable key: type: string required: - kind - key operator: type: string enum: - equals - not_equals - contains - not_contains - greater_than - less_than - gte - lte - is_empty - is_not_empty value: type: string maxLength: 1024 required: - source - operator responses: BadRequest: description: Malformed request, invalid ID/filter or unknown top-level field. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' PlanDisabled: description: Forms is disabled on the workspace plan. content: application/json: schema: type: object properties: error: type: string code: type: string enum: - plan_disabled feature: type: string enum: - forms Forbidden: description: Invitation, session, membership, or consent requirement not met. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Form not found in the account or not publicly available. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Stale version, duplicate response, or already used invitation. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: The request or definition is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Public admission, upload or AI quota exceeded. Reserved AI failures count. content: application/json: schema: $ref: '#/components/schemas/Error' ProviderError: description: AI could not produce a valid bounded response; reserved attempt counts. content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: Dependency/configuration unavailable; fail closed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your personal access token where supported, or a scoped API key (`hc_…`) created inside HueChat at Account → Developer API. Send it as `Authorization: Bearer `. ````