openapi: 3.0.4
info:
  title: Evolution Foundation - Auth Service - Setup Survey
  description: |
    Authenticated endpoint for saving and checking the onboarding survey.

    Used when the user logs in before completing the survey (e.g. when the
    one-time survey_token from the bootstrap response has expired).

    The setup wizard's initial submission goes through `/setup/survey`
    (authenticated via `X-Survey-Token` header). This authenticated path
    here is the fallback after a regular login.

    Available starting `v1.0.0-rc3`.
  version: 1.0.0
servers:
- url: https://app.evochat.ai
  description: Production
- url: http://localhost:3001
  description: Development
paths:
  /api/v1/setup_survey:
    get:
      operationId: get-setup-survey-status
      summary: Get Setup Survey Status
      description: Returns whether the current user has completed the onboarding survey.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Status retrieved
          content:
            application/json:
              schema:
                type: object
                required: [success, data, message]
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: object
                    properties:
                      completed: { type: boolean, example: false }
                  message: { type: string, example: "Survey status retrieved successfully" }
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: submit-setup-survey
      summary: Submit Setup Survey
      description: |
        Submits (creates or updates) the current user's setup survey
        response. Idempotent — if a response already exists for the user,
        it is updated; otherwise a new one is created.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                team_size:
                  type: string
                  description: "Team size bucket (e.g. '1-5', '6-20', '21-100', '100+')"
                daily_volume:
                  type: string
                  description: "Daily conversation volume bucket"
                main_channel:
                  type: string
                  description: "Primary channel used (whatsapp, instagram, etc.)"
                main_channel_other:
                  type: string
                  description: "Free-text if main_channel == 'other'"
                uses_ai:
                  type: string
                  description: "Whether the user currently uses AI agents"
                biggest_pain:
                  type: string
                  description: "Biggest operational pain point"
                crm_experience:
                  type: string
                  description: "Prior CRM experience level"
                main_goal:
                  type: string
                  description: "Main goal for adopting the CRM"
      responses:
        '200':
          description: Survey saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: object
                    properties:
                      completed: { type: boolean, example: true }
                  message: { type: string, example: "Survey saved successfully" }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              message: { type: string, example: "Unauthorized" }
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              message: { type: string }
              errors:
                type: object
                additionalProperties:
                  type: array
                  items: { type: string }