openapi.yaml

openapi: 3.1.0
info:
    title: Formbricks Hub API
    description: "Feedback record storage service for the Formbricks ecosystem.\n\n\U0001F4DA Full Documentation: https://hub.formbricks.com\n\U0001F680 Quick Start: https://hub.formbricks.com/quickstart\n\U0001F50C Connector Ecosystem: Coming soon"
    contact:
        name: Formbricks Team
        url: https://formbricks.com
        email: hola@formbricks.com
    license:
        name: Apache-2.0
        url: https://www.apache.org/licenses/LICENSE-2.0
    version: 1.0.0
servers:
    - url: http://localhost:8080
      description: Local development server
security:
    - ApiKeyAuth: []
paths:
    /health:
        get:
            tags:
                - Health
            summary: Health check
            description: Returns OK if the service is running
            operationId: health-check
            security: [] # No authentication required for health check
            responses:
                "200":
                    description: Service is healthy
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "OK"
    /v1/feedback-records:
        get:
            tags:
                - Feedback Records
            summary: List feedback records with filters
            description: Lists feedback records with optional filters and pagination
            operationId: list-feedback-records
            parameters:
                - name: tenant_id
                  in: query
                  description: Filter by tenant ID (for multi-tenant deployments). NULL bytes not allowed.
                  schema:
                    type: string
                    description: Filter by tenant ID (for multi-tenant deployments). NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
                - name: source_type
                  in: query
                  description: Filter by source type. NULL bytes not allowed.
                  schema:
                    type: string
                    description: Filter by source type. NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
                - name: source_id
                  in: query
                  description: Filter by source ID (NULL bytes not allowed)
                  schema:
                    type: string
                    description: Filter by source ID (NULL bytes not allowed)
                    pattern: '^[^\x00]*$'
                - name: field_id
                  in: query
                  description: Filter by field ID. NULL bytes not allowed.
                  schema:
                    type: string
                    pattern: '^[^\x00]*$'
                - name: field_group_id
                  in: query
                  description: Filter by field group ID (for ranking/matrix questions). NULL bytes not allowed.
                  schema:
                    type: string
                    description: Filter by field group ID (for ranking/matrix questions). NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
                - name: field_type
                  in: query
                  description: Filter by field type. NULL bytes not allowed.
                  schema:
                    type: string
                    description: Filter by field type. NULL bytes not allowed.
                    enum:
                        - text
                        - categorical
                        - nps
                        - csat
                        - ces
                        - rating
                        - number
                        - boolean
                        - date
                    pattern: '^[^\x00]*$'
                - name: user_identifier
                  in: query
                  description: Filter by user identifier. NULL bytes not allowed.
                  schema:
                    type: string
                    description: Filter by user identifier. NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
                - name: since
                  in: query
                  description: Filter by collected_at >= since (ISO 8601 format). Must be between 1970-01-01 and 2080-12-31.
                  schema:
                    type: string
                    format: date-time
                    description: Filter by collected_at >= since (ISO 8601 format). Must be between 1970-01-01 and 2080-12-31.
                - name: until
                  in: query
                  description: Filter by collected_at <= until (ISO 8601 format). Must be between 1970-01-01 and 2080-12-31.
                  schema:
                    type: string
                    format: date-time
                    description: Filter by collected_at <= until (ISO 8601 format). Must be between 1970-01-01 and 2080-12-31.
                - name: limit
                  in: query
                  description: Number of results to return (max 1000)
                  schema:
                    type: integer
                    description: Number of results to return (max 1000)
                    format: int64
                    default: 100
                    minimum: 1
                    maximum: 1000
                - name: offset
                  in: query
                  description: Number of results to skip
                  schema:
                    type: integer
                    description: Number of results to skip
                    format: int64
                    default: 0
                    minimum: 0
                    maximum: 2147483647
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListFeedbackRecordsOutputBody'
                            examples:
                                basic:
                                    summary: Basic list response
                                    value:
                                        data:
                                            - id: "018e1234-5678-9abc-def0-123456789abc"
                                              collected_at: "2024-01-15T10:30:00Z"
                                              created_at: "2024-01-15T10:30:00Z"
                                              updated_at: "2024-01-15T10:30:00Z"
                                              source_type: "survey"
                                              field_id: "q1"
                                              field_type: "rating"
                                              field_label: "How satisfied are you?"
                                              value_number: 9
                                              source_id: "survey-123"
                                              source_name: "Q1 NPS Survey"
                                              user_identifier: "user-abc-123"
                                              tenant_id: "org-123"
                                        total: 1
                                        limit: 100
                                        offset: 0
                default:
                    description: Error
                    content:
                        application/problem+json:
                            schema:
                                $ref: '#/components/schemas/ErrorModel'
                            examples:
                                validation_error:
                                    summary: Validation error
                                    value:
                                        type: "about:blank"
                                        title: "Bad Request"
                                        status: 400
                                        detail: "Validation failed"
                                        instance: "/v1/feedback-records"
                                        errors:
                                            - location: "body.field_id"
                                              message: "Field is required"
                                              value: null
        post:
            tags:
                - Feedback Records
            summary: Create a new feedback record
            description: Creates a new feedback record data point
            operationId: create-feedback-record
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateFeedbackRecordInputBody'
                        examples:
                            rating:
                                summary: Rating feedback
                                value:
                                    source_type: "survey"
                                    field_id: "q1"
                                    field_type: "rating"
                                    field_label: "How satisfied are you?"
                                    value_number: 9
                                    source_id: "survey-123"
                                    source_name: "Q1 NPS Survey"
                                    user_identifier: "user-abc-123"
                                    tenant_id: "org-123"
                                    language: "en"
                            text:
                                summary: Text feedback
                                value:
                                    source_type: "survey"
                                    field_id: "q2"
                                    field_type: "text"
                                    field_label: "What can we improve?"
                                    value_text: "Great service! Keep it up."
                                    source_id: "survey-123"
                                    source_name: "Q1 NPS Survey"
                                    user_identifier: "user-abc-123"
                                    tenant_id: "org-123"
                                    language: "en"
                            nps:
                                summary: NPS score
                                value:
                                    source_type: "survey"
                                    field_id: "nps"
                                    field_type: "nps"
                                    field_label: "How likely are you to recommend us?"
                                    value_number: 8
                                    source_id: "survey-123"
                                    source_name: "NPS Survey"
                                    user_identifier: "user-abc-123"
                                    tenant_id: "org-123"
                                    language: "en"
                            boolean:
                                summary: Boolean feedback
                                value:
                                    source_type: "survey"
                                    field_id: "q3"
                                    field_type: "boolean"
                                    field_label: "Would you use our service again?"
                                    value_boolean: true
                                    source_id: "survey-123"
                                    source_name: "Q1 NPS Survey"
                                    user_identifier: "user-abc-123"
                                    tenant_id: "org-123"
                                    language: "en"
                            ranking:
                                summary: Ranking question item
                                value:
                                    source_type: "survey"
                                    field_id: "feature_priority__reports"
                                    field_type: "number"
                                    field_label: "Reports"
                                    field_group_id: "feature_priority"
                                    field_group_label: "Rank these features by importance"
                                    value_number: 1
                                    response_id: "resp-abc-123"
                                    source_id: "survey-123"
                                    source_name: "Feature Priority Survey"
                                    user_identifier: "user-abc-123"
                                    tenant_id: "org-123"
                                    metadata:
                                        question_type: "ranking"
                                        total_items: 3
                            matrix:
                                summary: Matrix rating item
                                value:
                                    source_type: "survey"
                                    field_id: "feature_satisfaction__ease_of_use"
                                    field_type: "rating"
                                    field_label: "Ease of Use"
                                    field_group_id: "feature_satisfaction"
                                    field_group_label: "Rate your satisfaction with each feature"
                                    value_number: 4
                                    response_id: "resp-abc-123"
                                    source_id: "survey-123"
                                    source_name: "Feature Satisfaction Survey"
                                    user_identifier: "user-abc-123"
                                    tenant_id: "org-123"
                                    metadata:
                                        question_type: "matrix"
                required: true
            responses:
                "201":
                    description: Created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FeedbackRecordData'
                            examples:
                                created:
                                    summary: Created feedback record
                                    value:
                                        id: "018e1234-5678-9abc-def0-123456789abc"
                                        collected_at: "2024-01-15T10:30:00Z"
                                        created_at: "2024-01-15T10:30:00Z"
                                        updated_at: "2024-01-15T10:30:00Z"
                                        source_type: "survey"
                                        field_id: "q1"
                                        field_type: "rating"
                                        field_label: "How satisfied are you?"
                                        value_number: 9
                                        source_id: "survey-123"
                                        source_name: "Q1 NPS Survey"
                                        user_identifier: "user-abc-123"
                                        tenant_id: "org-123"
                                        language: "en"
                    links:
                        GetCreatedRecord:
                            operationId: get-feedback-record
                            parameters:
                                id: '$response.body#/id'
                            description: Retrieve the created feedback record by ID
                        UpdateCreatedRecord:
                            operationId: update-feedback-record
                            parameters:
                                id: '$response.body#/id'
                            description: Update the created feedback record by ID
                        DeleteCreatedRecord:
                            operationId: delete-feedback-record
                            parameters:
                                id: '$response.body#/id'
                            description: Delete the created feedback record by ID
                default:
                    description: Error
                    content:
                        application/problem+json:
                            schema:
                                $ref: '#/components/schemas/ErrorModel'
                            examples:
                                validation_error:
                                    summary: Validation error
                                    value:
                                        type: "about:blank"
                                        title: "Bad Request"
                                        status: 400
                                        detail: "Required field 'field_id' is missing"
                                        instance: "/v1/feedback-records"
        delete:
            tags:
                - Feedback Records
            summary: Bulk delete feedback records by user identifier
            description: Permanently deletes all feedback record data points matching the specified user_identifier. This endpoint supports GDPR Article 17 (Right to Erasure) requests.
            operationId: bulk-delete-feedback-records
            parameters:
                - name: user_identifier
                  in: query
                  description: Delete all records matching this user identifier (required). NULL bytes not allowed.
                  required: true
                  schema:
                    type: string
                    description: Delete all records matching this user identifier (required). NULL bytes not allowed.
                    minLength: 1
                    pattern: '^[^\x00]*$'
                - name: tenant_id
                  in: query
                  description: Filter by tenant ID (optional, for multi-tenant deployments). NULL bytes not allowed.
                  schema:
                    type: string
                    description: Filter by tenant ID (optional, for multi-tenant deployments). NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BulkDeleteFeedbackRecordsOutputBody'
                            examples:
                                success:
                                    summary: Successful bulk delete
                                    value:
                                        deleted_count: 42
                                        message: "Successfully deleted 42 feedback records"
                default:
                    description: Error
                    content:
                        application/problem+json:
                            schema:
                                $ref: '#/components/schemas/ErrorModel'
    /v1/feedback-records/{id}:
        get:
            tags:
                - Feedback Records
            summary: Get a feedback record by ID
            description: Retrieves a single feedback record data point by its UUID
            operationId: get-feedback-record
            parameters:
                - name: id
                  in: path
                  description: Feedback Record ID (UUID)
                  required: true
                  schema:
                    type: string
                    description: Feedback Record ID (UUID)
                    format: uuid
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FeedbackRecordData'
                default:
                    description: Error
                    content:
                        application/problem+json:
                            schema:
                                $ref: '#/components/schemas/ErrorModel'
        delete:
            tags:
                - Feedback Records
            summary: Delete a feedback record
            description: Permanently deletes a feedback record data point
            operationId: delete-feedback-record
            parameters:
                - name: id
                  in: path
                  description: Feedback Record ID (UUID)
                  required: true
                  schema:
                    type: string
                    description: Feedback Record ID (UUID)
                    format: uuid
            responses:
                "204":
                    description: No Content
                default:
                    description: Error
                    content:
                        application/problem+json:
                            schema:
                                $ref: '#/components/schemas/ErrorModel'
        patch:
            tags:
                - Feedback Records
            summary: Update a feedback record
            description: Updates specific fields of a feedback record data point
            operationId: update-feedback-record
            parameters:
                - name: id
                  in: path
                  description: Feedback Record ID (UUID)
                  required: true
                  schema:
                    type: string
                    description: Feedback Record ID (UUID)
                    format: uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateFeedbackRecordInputBody'
                        examples:
                            update_text:
                                summary: Update text value
                                value:
                                    value_text: "Updated feedback text"
                            update_number:
                                summary: Update numeric value
                                value:
                                    value_number: 10
                            update_metadata:
                                summary: Update metadata
                                value:
                                    metadata:
                                        tags:
                                            - "important"
                                            - "follow-up"
                                        priority: "high"
                            update_user:
                                summary: Update user identifier
                                value:
                                    user_identifier: "user-xyz-789"
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FeedbackRecordData'
                            examples:
                                updated:
                                    summary: Updated feedback record
                                    value:
                                        id: "018e1234-5678-9abc-def0-123456789abc"
                                        collected_at: "2024-01-15T10:30:00Z"
                                        created_at: "2024-01-15T10:30:00Z"
                                        updated_at: "2024-01-15T11:00:00Z"
                                        source_type: "survey"
                                        field_id: "q1"
                                        field_type: "rating"
                                        field_label: "How satisfied are you?"
                                        value_number: 10
                                        source_id: "survey-123"
                                        source_name: "Q1 NPS Survey"
                                        user_identifier: "user-abc-123"
                                        tenant_id: "org-123"
                                        language: "en"
                                        metadata:
                                            tags:
                                                - "important"
                                                - "follow-up"
                default:
                    description: Error
                    content:
                        application/problem+json:
                            schema:
                                $ref: '#/components/schemas/ErrorModel'
                            examples:
                                not_found:
                                    summary: Record not found
                                    value:
                                        type: "about:blank"
                                        title: "Not Found"
                                        status: 404
                                        detail: "Feedback record with ID '018e1234-5678-9abc-def0-123456789abc' not found"
                                        instance: "/v1/feedback-records/018e1234-5678-9abc-def0-123456789abc"
                                validation_error:
                                    summary: Validation error
                                    value:
                                        type: "about:blank"
                                        title: "Bad Request"
                                        status: 400
                                        detail: "Invalid update request"
                                        instance: "/v1/feedback-records/018e1234-5678-9abc-def0-123456789abc"
                                        errors:
                                            - location: "body.value_text"
                                              message: "Text value cannot be empty"
                                              value: ""
components:
    securitySchemes:
        ApiKeyAuth:
            type: http
            scheme: bearer
            bearerFormat: API Key
            description: API key authentication via Bearer token in Authorization header
    schemas:
        BulkDeleteFeedbackRecordsOutputBody:
            type: object
            additionalProperties: false
            properties:
                deleted_count:
                    type: integer
                    description: Number of records deleted
                    format: int64
                message:
                    type: string
                    description: Human-readable status message
            required:
                - deleted_count
                - message
        CreateFeedbackRecordInputBody:
            type: object
            additionalProperties: false
            properties:
                collected_at:
                    type: string
                    description: When the feedback was collected (defaults to now). Must be between 1970-01-01 and 2080-12-31.
                    format: date-time
                field_id:
                    type: string
                    description: Identifier for the question/field. NULL bytes not allowed.
                    examples:
                        - q1
                    minLength: 1
                    maxLength: 255
                    pattern: '^[^\x00]*$'
                field_label:
                    type: string
                    description: The actual question text
                    examples:
                        - How satisfied are you?
                field_group_id:
                    type: string
                    description: Stable identifier grouping related fields (for ranking, matrix, grid questions). NULL bytes not allowed.
                    examples:
                        - feature_priority
                    maxLength: 255
                    pattern: '^[^\x00]*$'
                field_group_label:
                    type: string
                    description: Human-readable question text for the group
                    examples:
                        - Rank these features by importance
                field_type:
                    type: string
                    description: 'Field type: text (enrichable), categorical, nps, csat, ces, rating, number, boolean, date'
                    examples:
                        - rating
                    enum:
                        - text
                        - categorical
                        - nps
                        - csat
                        - ces
                        - rating
                        - number
                        - boolean
                        - date
                    minLength: 1
                    maxLength: 255
                language:
                    type: string
                    description: ISO language code. NULL bytes not allowed.
                    examples:
                        - en
                    maxLength: 10
                    pattern: '^[^\x00]*$'
                metadata:
                    type: object
                    description: User agent, device, location, referrer, tags, etc. NULL bytes (\x00 or \u0000) are not allowed in JSON keys or values.
                    additionalProperties: {}
                source_id:
                    type: string
                    description: Reference to survey/form/ticket ID
                    examples:
                        - survey-123
                source_name:
                    type: string
                    description: Human-readable name
                    examples:
                        - Q1 NPS Survey
                source_type:
                    type: string
                    description: Type of feedback source (e.g., survey, review, feedback_form). NULL bytes not allowed.
                    examples:
                        - survey
                    minLength: 1
                    maxLength: 255
                    pattern: '^[^\x00]*$'
                tenant_id:
                    type: string
                    description: Tenant/organization identifier for multi-tenancy. NULL bytes not allowed.
                    examples:
                        - org-123
                    maxLength: 255
                    pattern: '^[^\x00]*$'
                user_identifier:
                    type: string
                    description: Anonymous ID or email hash
                    examples:
                        - user-abc-123
                value_boolean:
                    type: boolean
                    description: For yes/no questions
                    examples:
                        - true
                value_date:
                    type: string
                    description: For date responses. Must be between 1970-01-01 and 2080-12-31.
                    format: date-time
                value_number:
                    type: number
                    description: For ratings, NPS scores, numeric responses. Must be between -1e15 and +1e15.
                    format: double
                    minimum: -1000000000000000
                    maximum: 1000000000000000
                    examples:
                        - 9
                value_text:
                    type: string
                    description: For open-ended text responses. NULL bytes not allowed.
                    examples:
                        - Great service!
                    pattern: '^[^\x00]*$'
            required:
                - source_type
                - field_id
                - field_type
        ErrorDetail:
            type: object
            additionalProperties: false
            properties:
                location:
                    type: string
                    description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
                message:
                    type: string
                    description: Error message text
                value:
                    description: The value at the given location
        ErrorModel:
            type: object
            additionalProperties: false
            properties:
                detail:
                    type: string
                    description: A human-readable explanation specific to this occurrence of the problem.
                    examples:
                        - Property foo is required but is missing.
                errors:
                    type: array
                    description: Optional list of individual error details
                    items:
                        $ref: '#/components/schemas/ErrorDetail'
                instance:
                    type: string
                    description: A URI reference that identifies the specific occurrence of the problem.
                    format: uri
                    examples:
                        - https://example.com/error-log/abc123
                status:
                    type: integer
                    description: HTTP status code
                    format: int64
                    examples:
                        - 400
                title:
                    type: string
                    description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
                    examples:
                        - Bad Request
                type:
                    type: string
                    description: A URI reference to human-readable documentation for the error.
                    format: uri
                    default: about:blank
                    examples:
                        - https://example.com/errors/example
        FeedbackRecordData:
            type: object
            additionalProperties: false
            properties:
                collected_at:
                    type: string
                    description: When the feedback was collected
                    format: date-time
                created_at:
                    type: string
                    description: When this record was created
                    format: date-time
                field_id:
                    type: string
                    description: Identifier for the question/field
                field_label:
                    type: string
                    description: The actual question text
                field_group_id:
                    type: string
                    description: Stable identifier grouping related fields (for ranking, matrix, grid questions)
                field_group_label:
                    type: string
                    description: Human-readable question text for the group
                field_type:
                    type: string
                    description: Type of field
                    enum:
                        - text
                        - categorical
                        - nps
                        - csat
                        - ces
                        - rating
                        - number
                        - boolean
                        - date
                id:
                    type: string
                    format: uuid
                    description: UUIDv7 primary key
                language:
                    type: string
                    description: ISO language code. NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
                metadata:
                    type: object
                    description: Additional context
                    additionalProperties: {}
                source_id:
                    type: string
                    description: Reference to survey/form/ticket ID
                source_name:
                    type: string
                    description: Human-readable name
                source_type:
                    type: string
                    description: Type of feedback source
                tenant_id:
                    type: string
                    description: Tenant/organization identifier. NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
                updated_at:
                    type: string
                    description: When this record was last updated
                    format: date-time
                user_identifier:
                    type: string
                    description: User identifier
                value_boolean:
                    type: boolean
                    description: Boolean response
                value_date:
                    type: string
                    description: Date response
                    format: date-time
                value_number:
                    type: number
                    description: Numeric response
                    format: double
                value_text:
                    type: string
                    description: Text response. NULL bytes not allowed.
                    pattern: '^[^\x00]*$'
            required:
                - id
                - collected_at
                - created_at
                - updated_at
                - source_type
                - field_id
                - field_type
        ListFeedbackRecordsOutputBody:
            type: object
            additionalProperties: false
            properties:
                data:
                    type: array
                    description: List of feedback records
                    items:
                        $ref: '#/components/schemas/FeedbackRecordData'
                limit:
                    type: integer
                    description: Limit used in query
                    format: int64
                offset:
                    type: integer
                    description: Offset used in query
                    format: int64
                total:
                    type: integer
                    description: Total count of feedback records matching filters
                    format: int64
            required:
                - data
                - total
                - limit
                - offset
        UpdateFeedbackRecordInputBody:
            type: object
            additionalProperties: false
            properties:
                language:
                    type: string
                    description: Update language. NULL bytes not allowed.
                    maxLength: 10
                    pattern: '^[^\x00]*$'
                metadata:
                    type: object
                    description: Update metadata. NULL bytes (\x00 or \u0000) are not allowed in JSON keys or values.
                    additionalProperties: {}
                user_identifier:
                    type: string
                    description: Update user identifier
                value_boolean:
                    type: boolean
                    description: Update boolean response
                value_date:
                    type: string
                    description: Update date response. Must be between 1970-01-01 and 2080-12-31.
                    format: date-time
                value_number:
                    type: number
                    description: Update numeric response. Must be between -1e15 and +1e15.
                    format: double
                    minimum: -1000000000000000
                    maximum: 1000000000000000
                value_text:
                    type: string
                    description: Update text response. NULL bytes not allowed.
                    pattern: '^[^\x00]*$'