openapi: 3.0.3
info:
  title: Survicate Data Export Personal Data Surveys API
  description: 'The Survicate Data Export API (v2) allows retrieval of survey data collected in your Survicate account. It exposes resources for surveys, responses, respondents, and personal data management to integrate feedback into databases, CRMs, and custom solutions.

    '
  version: '2'
  contact:
    name: Survicate Developer Documentation
    url: https://developers.survicate.com/data-export/
  termsOfService: https://survicate.com/terms/
  license:
    name: Proprietary
    url: https://survicate.com/terms/
servers:
- url: https://data.survicate.com
  description: Survicate Data Export API base URL
security:
- BasicAuth: []
tags:
- name: Surveys
  description: Operations related to surveys and their questions
paths:
  /v2/surveys:
    get:
      operationId: listSurveys
      summary: List all surveys
      description: Returns a paginated list of all surveys in the Survicate account.
      tags:
      - Surveys
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        description: Number of surveys per page
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: A list of surveys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/surveys/{surveyId}:
    get:
      operationId: getSurvey
      summary: Retrieve survey information
      description: Returns detailed information about a specific survey.
      tags:
      - Surveys
      parameters:
      - $ref: '#/components/parameters/surveyId'
      responses:
        '200':
          description: Survey details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Survey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v2/surveys/{surveyId}/questions:
    get:
      operationId: listSurveyQuestions
      summary: List questions for a survey
      description: Returns all questions for a specific survey along with their answer options.
      tags:
      - Surveys
      parameters:
      - $ref: '#/components/parameters/surveyId'
      responses:
        '200':
          description: A list of questions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Question:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the question
        survey_id:
          type: string
          description: Identifier of the parent survey
        type:
          type: string
          description: Type of question (e.g., nps, rating, text, multiple_choice)
          enum:
          - nps
          - rating
          - text
          - multiple_choice
          - checkbox
          - dropdown
        content:
          type: string
          description: The question text
        position:
          type: integer
          description: Position/order of the question in the survey
        answers:
          type: array
          description: Available answer options for closed-ended questions
          items:
            $ref: '#/components/schemas/AnswerOption'
    Survey:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the survey
        name:
          type: string
          description: Name of the survey
        status:
          type: string
          description: Status of the survey (e.g., active, paused, closed)
          enum:
          - active
          - paused
          - closed
        created_at:
          type: string
          format: date-time
          description: Date and time when the survey was created
        updated_at:
          type: string
          format: date-time
          description: Date and time when the survey was last updated
        responses_count:
          type: integer
          description: Total number of responses collected
        questions_count:
          type: integer
          description: Total number of questions in the survey
    SurveyList:
      type: object
      allOf:
      - $ref: '#/components/schemas/Pagination'
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Survey'
    AnswerOption:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the answer option
        content:
          type: string
          description: Text of the answer option
        position:
          type: integer
          description: Position/order of the answer option
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number
        per_page:
          type: integer
          description: Number of items per page
        total:
          type: integer
          description: Total number of items
        total_pages:
          type: integer
          description: Total number of pages
    Error:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
        code:
          type: string
          description: An error code identifier
    QuestionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Question'
  parameters:
    surveyId:
      name: surveyId
      in: path
      required: true
      description: The unique identifier of the survey
      schema:
        type: string
  responses:
    TooManyRequests:
      description: 'Rate limit exceeded. Survicate allows up to 5 concurrent requests and up to 1000 requests per minute per workspace.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed or API key is missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Use your Survicate API key as the value for Basic authentication. The API key can be found in the Survicate panel under Surveys Settings > Access Keys. Format: `Basic {{apiKey}}`

        '