openapi: 3.1.0
info:
  title: Formbricks API
  description: Manage Formbricks ressources programmatically.
  version: 2.0.0
servers:
  - url: https://app.formbricks.com/api
    description: Formbricks Cloud
tags:
  - name: Responses
    description: Operations for managing responses.
  - name: Contacts
    description: Operations for managing contacts.
  - name: Contact Attributes
    description: Operations for managing contact attributes.
  - name: Contact Attributes Keys
    description: Operations for managing contact attributes keys.
paths:
  /responses:
    get:
      operationId: getResponses
      summary: Get responses
      description: Gets responses from the database.
      tags:
        - responses
      parameters:
        - in: query
          name: limit
          schema:
            type: number
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: skip
          schema:
            type: number
            minimum: 0
            default: 0
        - in: query
          name: sortBy
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
            default: createdAt
        - in: query
          name: order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - in: query
          name: startDate
          schema:
            type: string
          required: true
        - in: query
          name: endDate
          schema:
            type: string
          required: true
        - in: query
          name: surveyId
          schema:
            type: string
          required: true
        - in: query
          name: contactId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Responses retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/response"
    post:
      operationId: createResponse
      summary: Create a response
      description: Creates a response in the database.
      tags:
        - responses
      requestBody:
        required: true
        description: The response to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/responseCreate"
      responses:
        "201":
          description: Response created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
  /responses/{id}:
    get:
      operationId: getResponse
      summary: Get a response
      description: Gets a response from the database.
      tags:
        - responses
      parameters:
        - in: path
          name: id
          description: The ID of the response
          schema:
            $ref: "#/components/schemas/responseId"
          required: true
      responses:
        "200":
          description: Response retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
    put:
      operationId: updateResponse
      summary: Update a response
      description: Updates a response in the database.
      tags:
        - responses
      parameters:
        - in: path
          name: id
          description: The ID of the response
          schema:
            $ref: "#/components/schemas/responseId"
          required: true
      requestBody:
        required: true
        description: The response to update
        content:
          application/json:
            schema:
              type: object
              properties:
                createdAt:
                  type: string
                updatedAt:
                  type: string
                environmentId:
                  type: string
                surveyId:
                  type: string
                userId:
                  type:
                    - string
                    - "null"
                displayId:
                  type:
                    - string
                    - "null"
                singleUseId:
                  type:
                    - string
                    - "null"
                finished:
                  type: boolean
                endingId:
                  type:
                    - string
                    - "null"
                language:
                  type: string
                data:
                  type: object
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: string
                variables:
                  type: object
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                ttc:
                  type: object
                  additionalProperties:
                    type: number
                meta:
                  type: object
                  properties:
                    source:
                      type: string
                    url:
                      type: string
                    userAgent:
                      type: object
                      properties:
                        browser:
                          type: string
                        device:
                          type: string
                        os:
                          type: string
                    country:
                      type: string
                    action:
                      type: string
              required:
                - environmentId
                - surveyId
                - finished
                - data
      responses:
        "200":
          description: Response updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
    delete:
      operationId: deleteResponse
      summary: Delete a response
      description: Deletes a response from the database.
      tags:
        - responses
      parameters:
        - in: path
          name: id
          description: The ID of the response
          schema:
            $ref: "#/components/schemas/responseId"
          required: true
      responses:
        "200":
          description: Response deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/response"
  /contacts:
    get:
      operationId: getContacts
      summary: Get contacts
      description: Gets contacts from the database.
      tags:
        - contacts
      parameters:
        - in: query
          name: limit
          schema:
            type: number
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: skip
          schema:
            type: number
            minimum: 0
            default: 0
        - in: query
          name: sortBy
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
            default: createdAt
        - in: query
          name: order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - in: query
          name: startDate
          schema:
            type: string
        - in: query
          name: endDate
          schema:
            type: string
      responses:
        "200":
          description: Contacts retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/contact"
    post:
      operationId: createContact
      summary: Create a contact
      description: Creates a contact in the database.
      tags:
        - contacts
      requestBody:
        required: true
        description: The contact to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/contactCreate"
      responses:
        "201":
          description: Contact created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contact"
  /contacts/{id}:
    get:
      operationId: getContact
      summary: Get a contact
      description: Gets a contact from the database.
      tags:
        - contacts
      parameters:
        - in: path
          name: contactId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Contact retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contact"
    put:
      operationId: updateContact
      summary: Update a contact
      description: Updates a contact in the database.
      tags:
        - contacts
      parameters:
        - in: path
          name: contactId
          schema:
            type: string
          required: true
      requestBody:
        required: true
        description: The response to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/contactCreate"
      responses:
        "200":
          description: Response updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contact"
    delete:
      operationId: deleteContact
      summary: Delete a contact
      description: Deletes a contact from the database.
      tags:
        - contacts
      parameters:
        - in: path
          name: contactId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Contact deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contact"
  /contact-attributes:
    get:
      operationId: getContactAttributes
      summary: Get contact attributes
      description: Gets contact attributes from the database.
      tags:
        - contact-attributes
      parameters:
        - in: query
          name: limit
          schema:
            type: number
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: skip
          schema:
            type: number
            minimum: 0
            default: 0
        - in: query
          name: sortBy
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
            default: createdAt
        - in: query
          name: order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - in: query
          name: startDate
          schema:
            type: string
        - in: query
          name: endDate
          schema:
            type: string
      responses:
        "200":
          description: Contact attributes retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/contactAttribute"
    post:
      operationId: createContactAttribute
      summary: Create a contact attribute
      description: Creates a contact attribute in the database.
      tags:
        - contact-attributes
      requestBody:
        required: true
        description: The contact attribute to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/contactAttributeInput"
      responses:
        "201":
          description: Contact attribute created successfully.
  /contact-attributes/{id}:
    get:
      operationId: getContactAttribute
      summary: Get a contact attribute
      description: Gets a contact attribute from the database.
      tags:
        - contact-attributes
      parameters:
        - in: path
          name: contactAttributeId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Contact retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contactAttribute"
    put:
      operationId: updateContactAttribute
      summary: Update a contact attribute
      description: Updates a contact attribute in the database.
      tags:
        - contact-attributes
      parameters:
        - in: path
          name: contactAttributeId
          schema:
            type: string
          required: true
      requestBody:
        required: true
        description: The response to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/contactAttributeInput"
      responses:
        "200":
          description: Response updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contactAttribute"
    delete:
      operationId: deleteContactAttribute
      summary: Delete a contact attribute
      description: Deletes a contact attribute from the database.
      tags:
        - contact-attributes
      parameters:
        - in: path
          name: contactAttributeId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Contact deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contactAttribute"
  /contact-attribute-keys:
    get:
      operationId: getContactAttributeKeys
      summary: Get contact attribute keys
      description: Gets contact attribute keys from the database.
      tags:
        - contact-attribute-keys
      parameters:
        - in: query
          name: limit
          schema:
            type: number
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: skip
          schema:
            type: number
            minimum: 0
            default: 0
        - in: query
          name: sortBy
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
            default: createdAt
        - in: query
          name: order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - in: query
          name: startDate
          schema:
            type: string
        - in: query
          name: endDate
          schema:
            type: string
      responses:
        "200":
          description: Contact attribute keys retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/contactAttributeKey"
    post:
      operationId: createContactAttributeKey
      summary: Create a contact attribute key
      description: Creates a contact attribute key in the database.
      tags:
        - contact-attribute-keys
      requestBody:
        required: true
        description: The contact attribute key to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/contactAttributeKeyInput"
      responses:
        "201":
          description: Contact attribute key created successfully.
  /contact-attribute-keys/{id}:
    get:
      operationId: getContactAttributeKey
      summary: Get a contact attribute key
      description: Gets a contact attribute key from the database.
      tags:
        - contact-attribute-keys
      parameters:
        - in: path
          name: contactAttributeKeyId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Contact attribute key retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contactAttributeKey"
    put:
      operationId: updateContactAttributeKey
      summary: Update a contact attribute key
      description: Updates a contact attribute key in the database.
      tags:
        - contact-attribute-keys
      parameters:
        - in: path
          name: contactAttributeKeyId
          schema:
            type: string
          required: true
      requestBody:
        required: true
        description: The contact attribute key to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/contactAttributeKeyInput"
      responses:
        "200":
          description: Contact attribute key updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contactAttributeKey"
    delete:
      operationId: deleteContactAttributeKey
      summary: Delete a contact attribute key
      description: Deletes a contact attribute key from the database.
      tags:
        - contact-attribute-keys
      parameters:
        - in: path
          name: contactAttributeId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Contact attribute key deleted successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/contactAttributeKey"
components:
  schemas:
    response:
      type: object
      properties:
        id:
          type: string
          description: The ID of the response
        createdAt:
          type: string
          description: The date and time the response was created
          example: 2021-01-01T00:00:00.000Z
        updatedAt:
          type: string
          description: The date and time the response was last updated
          example: 2021-01-01T00:00:00.000Z
        finished:
          type: boolean
          description: Whether the response is finished
          example: true
        surveyId:
          type: string
          description: The ID of the survey
        contactId:
          type:
            - string
            - "null"
          description: The ID of the contact
        endingId:
          type:
            - string
            - "null"
          description: The ID of the ending
        data:
          type: object
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: array
                items:
                  type: string
              - type: object
                additionalProperties:
                  type: string
          description: The data of the response
          example: &a1
            question1: answer1
            question2: 2
            question3:
              - answer3
              - answer4
            question4:
              subquestion1: answer5
        variables:
          type: object
          additionalProperties:
            anyOf:
              - type: string
              - type: number
          description: The variables of the response
          example: &a2
            variable1: answer1
            variable2: 2
        ttc:
          type: object
          additionalProperties:
            type: number
          description: The TTC of the response
          example: &a3
            question1: 10
            question2: 20
        meta:
          type: object
          properties:
            source:
              type: string
              description: The source of the response
              example: https://example.com
            url:
              type: string
              description: The URL of the response
              example: https://example.com
            userAgent:
              type: object
              properties:
                browser:
                  type: string
                os:
                  type: string
                device:
                  type: string
            country:
              type: string
            action:
              type: string
          description: The meta data of the response
          example: &a4
            source: https://example.com
            url: https://example.com
            userAgent:
              browser: Chrome
              os: Windows
              device: Desktop
            country: US
            action: click
        contactAttributes:
          type:
            - object
            - "null"
          additionalProperties:
            type: string
          description: The attributes of the contact
          example:
            attribute1: value1
            attribute2: value2
        singleUseId:
          type:
            - string
            - "null"
          description: The single use ID of the response
        language:
          type:
            - string
            - "null"
          description: The language of the response
          example: en
        displayId:
          type:
            - string
            - "null"
          description: The display ID of the response
      required:
        - id
        - createdAt
        - updatedAt
        - finished
        - surveyId
        - contactId
        - endingId
        - data
        - variables
        - ttc
        - meta
        - contactAttributes
        - singleUseId
        - language
        - displayId
    contact:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the contact
        userId:
          type:
            - string
            - "null"
          description: Optional external user identifier
        createdAt:
          type: string
          description: When the contact was created
          example: 2021-01-01T00:00:00.000Z
        updatedAt:
          type: string
          description: When the contact was last updated
          example: 2021-01-01T00:00:00.000Z
        environmentId:
          type: string
          description: The environment this contact belongs to
      required:
        - id
        - userId
        - createdAt
        - updatedAt
        - environmentId
    contactAttribute:
      type: object
      properties:
        id:
          type: string
          description: The ID of the contact attribute
        createdAt:
          type: string
          description: The date and time the contact attribute was created
          example: 2021-01-01T00:00:00.000Z
        updatedAt:
          type: string
          description: The date and time the contact attribute was last updated
          example: 2021-01-01T00:00:00.000Z
        attributeKeyId:
          type: string
          description: The ID of the attribute key
        contactId:
          type: string
          description: The ID of the contact
        value:
          type: string
          description: The value of the attribute
          example: example@email.com
      required:
        - id
        - createdAt
        - updatedAt
        - attributeKeyId
        - contactId
        - value
    contactAttributeKey:
      type: object
      properties:
        id:
          type: string
          description: The ID of the contact attribute key
        createdAt:
          type: string
          description: The date and time the contact attribute key was created
          example: 2021-01-01T00:00:00.000Z
        updatedAt:
          type: string
          description: The date and time the contact attribute key was last updated
          example: 2021-01-01T00:00:00.000Z
        isUnique:
          type: boolean
          description: Whether the attribute must have unique values across contacts
          example: false
        key:
          type: string
          description: The attribute identifier used in the system
          example: email
        name:
          type:
            - string
            - "null"
          description: Display name for the attribute
          example: Email Address
        description:
          type:
            - string
            - "null"
          description: Description of the attribute
          example: The user's email address
        type:
          type: string
          enum:
            - default
            - custom
          description: Whether this is a default or custom attribute
          example: custom
        environmentId:
          type: string
          description: The ID of the environment this attribute belongs to
      required:
        - id
        - createdAt
        - updatedAt
        - isUnique
        - key
        - name
        - description
        - type
        - environmentId
    responseCreate:
      type: object
      properties:
        createdAt:
          type: string
          description: The date and time the response was created
          example: 2021-01-01T00:00:00.000Z
        updatedAt:
          type: string
          description: The date and time the response was last updated
          example: 2021-01-01T00:00:00.000Z
        surveyId:
          type: string
          description: The ID of the survey
        displayId:
          type:
            - string
            - "null"
          description: The display ID of the response
        singleUseId:
          type:
            - string
            - "null"
          description: The single use ID of the response
        finished:
          type: boolean
          description: Whether the response is finished
          example: true
        endingId:
          type:
            - string
            - "null"
          description: The ID of the ending
        language:
          type:
            - string
            - "null"
          description: The language of the response
          example: en
        data:
          type: object
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: array
                items:
                  type: string
              - type: object
                additionalProperties:
                  type: string
          description: The data of the response
          example: *a1
        variables:
          type: object
          additionalProperties:
            anyOf:
              - type: string
              - type: number
          description: The variables of the response
          example: *a2
        ttc:
          type: object
          additionalProperties:
            type: number
          description: The TTC of the response
          example: *a3
        meta:
          type: object
          properties:
            source:
              type: string
              description: The source of the response
              example: https://example.com
            url:
              type: string
              description: The URL of the response
              example: https://example.com
            userAgent:
              type: object
              properties:
                browser:
                  type: string
                os:
                  type: string
                device:
                  type: string
            country:
              type: string
            action:
              type: string
          description: The meta data of the response
          example: *a4
      required:
        - surveyId
        - finished
        - data
      description: A response to create
    responseId:
      type: string
      description: The ID of the response
    contactCreate:
      type: object
      properties:
        userId:
          type:
            - string
            - "null"
          description: Optional external user identifier
        environmentId:
          type: string
          description: The environment this contact belongs to
      required:
        - environmentId
      description: A contact to create
    contactAttributeInput:
      type: object
      properties:
        attributeKeyId:
          type: string
          description: The ID of the attribute key
        contactId:
          type: string
          description: The ID of the contact
        value:
          type: string
          description: The value of the attribute
          example: example@email.com
      required:
        - attributeKeyId
        - contactId
        - value
      description: Input data for creating or updating a contact attribute
    contactAttributeKeyInput:
      type: object
      properties:
        key:
          type: string
          description: The attribute identifier used in the system
          example: email
        name:
          type:
            - string
            - "null"
          description: Display name for the attribute
          example: Email Address
        description:
          type:
            - string
            - "null"
          description: Description of the attribute
          example: The user's email address
        type:
          type: string
          enum:
            - default
            - custom
          description: Whether this is a default or custom attribute
          example: custom
        environmentId:
          type: string
          description: The ID of the environment this attribute belongs to
      required:
        - key
        - name
        - description
        - type
        - environmentId
      description: Input data for creating or updating a contact attribute