Skip to main content

Forms

Forms are structured feedback collections with typed questions (ratings, text, emoji, image choice, etc.). They are separate from rooms and have their own public submission URLs.

All management endpoints require authentication. Submission endpoints are public.

List forms​

GET /api/forms

Returns all forms in the organization.

Create a form​

POST /api/forms
{
  "title": "Event Feedback",
  "description": "Tell us about your experience",
  "questions": [
    {
      "type": "rating",
      "text": "How would you rate the event?",
      "required": true
    },
    {
      "type": "text",
      "text": "Any additional comments?",
      "required": false
    }
  ]
}

Question types: rating, text, emoji, options, image_choice, scale

Response 201 — returns the created form including its generated slug.

Get a form​

GET /api/forms/:formId

Update a form​

PUT /api/forms/:formId

Accepts a partial form object. Only provided fields are updated.

Delete a form​

DELETE /api/forms/:formId

Also deletes associated question images from storage.

Clone a form​

POST /api/forms/:formId/clone

Creates a copy of the form with a new slug. Useful for reusing question sets across events.

Toggle active status​

PUT /api/forms/:formId/active
{ "active": false }

Public form endpoints​

Get form by slug​

GET /api/forms/public/:slug

Returns the form structure for rendering. No auth required.

Submit a response​

POST /api/forms/public/:slug/submit
{
  "responses": [
    { "questionId": "q1", "value": 4 },
    { "questionId": "q2", "value": "Great event, very organized." }
  ]
}

Rate limited — 10 submissions per IP per 15 minutes.

Analytics & insights​

Form analytics​

GET /api/forms/analytics

Returns aggregated response counts and completion rates across all forms.

Form statistics​

GET /api/forms/:formId/stats

Per-question breakdown: response counts, average ratings, option distributions.

Form responses​

GET /api/forms/:formId/responses

Paginated list of all individual responses.

Analyse responses (AI)​

GET /api/forms/:formId/analyze

Triggers AI analysis of responses. Returns themes, sentiment, and key findings.

Get saved analyses​

GET /api/forms/:formId/analyses

Returns previously generated AI analyses for the form.

Summarize text responses​

POST /api/forms/:formId/summarize-text
{ "questionId": "q2" }

Returns an AI-generated summary of all free-text responses for a question.

Text summaries​

GET /api/forms/:formId/text-summaries

Returns all saved text summaries for the form.

Word cloud data​

GET /api/forms/formcloud

Returns word frequency data across all form text responses for rendering a word cloud.

Image uploads​

Upload question image​

POST /api/forms/:formId/questions/:questionId/upload-image
Content-Type: multipart/form-data

Maximum file size: 5 MB.

Delete question image​

DELETE /api/forms/:formId/questions/:questionId/delete-image

Upload image choice option​

POST /api/forms/:formId/questions/:questionId/options/:optionId/upload-image
Content-Type: multipart/form-data

Delete image choice option​

DELETE /api/forms/:formId/questions/:questionId/options/:optionId/delete-image