Feedback1 Public Forms API

openapi: 3.2.0
info:
  title: Feedback1 Public Public Forms API
  description: '## Feedback1 Public API


    REST API for programmatic access to Feedback1 data.


    ### Authentication


    All endpoints require a Bearer token (API key) in the `Authorization` header:


    ```

    Authorization: Bearer your_api_key_here

    ```


    You can create API keys in the Feedback1 dashboard under Settings > API Keys.


    ### Rate Limits


    - 200 requests per minute per API key

    - Rate limit headers are included in responses


    ### Base URL


    ```

    https://app.feedback1.ai/api/v1

    ```'
  version: 1.0.0
servers:
- url: /api/v1
tags:
- name: public-forms
paths:
  /public/forms/{form_id}:
    get:
      tags:
      - public-forms
      summary: Get Public Form
      description: 'Get a public form for rendering.


        This endpoint is used by the userportal to render the form.

        Only returns forms that are both public and active.'
      operationId: get_public_form_public_forms__form_id__get
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFormResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    head:
      tags:
      - public-forms
      summary: Check Form Exists
      description: 'Check if a public form exists.


        Used by userportal for preflight checks.

        Returns 200 if form exists and is public/active, 404 otherwise.'
      operationId: check_form_exists_public_forms__form_id__head
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          title: Form Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /public/forms/{form_id}/submit:
    post:
      tags:
      - public-forms
      summary: Submit Form
      description: 'Submit a form response.


        This endpoint:

        1. Validates all required fields are answered

        2. Creates a FormResponse record

        3. Creates FormResponseAnswer records for each answer

        4. Optionally creates a Feedback item (if configured in form settings)'
      operationId: submit_form_public_forms__form_id__submit_post
      parameters:
      - name: form_id
        in: path
        required: true
        schema:
          type: string
          title: Form Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSubmission'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFormSubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FormSubmission:
      properties:
        answers:
          items:
            $ref: '#/components/schemas/FormResponseAnswerBase'
          type: array
          title: Answers
        respondent_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Respondent Email
        respondent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Respondent Name
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        turnstile_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Turnstile Token
      type: object
      required:
      - answers
      title: FormSubmission
      description: Submit form response (public endpoint)
    PublicFormResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        form_type:
          $ref: '#/components/schemas/FormTypeEnum'
        settings:
          $ref: '#/components/schemas/FormSettings'
        blocks:
          items:
            $ref: '#/components/schemas/PublicFormBlockResponse'
          type: array
          title: Blocks
        product_name:
          type: string
          title: Product Name
        product_logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Logo Url
      type: object
      required:
      - id
      - name
      - form_type
      - settings
      - blocks
      - product_name
      title: PublicFormResponse
      description: Public form response (for rendering form)
    FormTypeEnum:
      type: string
      enum:
      - form
      - survey
      title: FormTypeEnum
      description: Form type enum
    BlockTypeEnum:
      type: string
      enum:
      - short_text
      - long_text
      - single_choice
      - multiple_choice
      - rating
      - nps
      - email
      - date
      - file_upload
      - heading
      - paragraph
      - divider
      - image
      title: BlockTypeEnum
      description: Block type enum - all available form block types
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FormSettings:
      properties:
        theme:
          type: string
          enum:
          - light
          - dark
          - system
          title: Theme
          default: light
        primary_color:
          type: string
          title: Primary Color
          default: '#3B82F6'
        show_logo:
          type: boolean
          title: Show Logo
          default: true
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
        thank_you_message:
          type: string
          title: Thank You Message
          default: Thank you for your response!
        thank_you_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Thank You Description
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
        redirect_delay_seconds:
          type: integer
          title: Redirect Delay Seconds
          default: 3
        show_progress_bar:
          type: boolean
          title: Show Progress Bar
          default: true
        allow_save_draft:
          type: boolean
          title: Allow Save Draft
          default: false
        require_all_fields:
          type: boolean
          title: Require All Fields
          default: false
        send_email_notification:
          type: boolean
          title: Send Email Notification
          default: false
        notification_emails:
          items:
            type: string
          type: array
          title: Notification Emails
          default: []
        create_feedback_on_submit:
          type: boolean
          title: Create Feedback On Submit
          default: true
        contact_email_block_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Contact Email Block Id
      type: object
      title: FormSettings
      description: Form-level settings
    PublicFormSubmitResponse:
      properties:
        success:
          type: boolean
          title: Success
        response_id:
          type: string
          title: Response Id
        thank_you_message:
          type: string
          title: Thank You Message
        thank_you_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Thank You Description
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
        redirect_delay_seconds:
          type: integer
          title: Redirect Delay Seconds
          default: 3
      type: object
      required:
      - success
      - response_id
      - thank_you_message
      title: PublicFormSubmitResponse
      description: Response after submitting form
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PublicFormBlockResponse:
      properties:
        id:
          type: integer
          title: Id
        block_type:
          $ref: '#/components/schemas/BlockTypeEnum'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        placeholder:
          anyOf:
          - type: string
          - type: 'null'
          title: Placeholder
        is_required:
          type: boolean
          title: Is Required
        settings:
          additionalProperties: true
          type: object
          title: Settings
          default: {}
        order:
          type: integer
          title: Order
        page:
          type: integer
          title: Page
      type: object
      required:
      - id
      - block_type
      - is_required
      - order
      - page
      title: PublicFormBlockResponse
      description: Public block response (for rendering form)
    FormResponseAnswerBase:
      properties:
        block_id:
          type: integer
          title: Block Id
        answer_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Answer Value
        answer_json:
          anyOf:
          - {}
          - type: 'null'
          title: Answer Json
      type: object
      required:
      - block_id
      title: FormResponseAnswerBase
      description: Base answer schema
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer