> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit structured feedback or a question



## OpenAPI

````yaml /api-reference/openapi.json post /v1/feedback
openapi: 3.0.0
info:
  title: WattShift API
  description: An API for the WattShift Service (https://wattshift.com/partners)
  version: '1.0'
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/feedback:
    post:
      tags:
        - feedback
      summary: Submit structured feedback or a question
      operationId: submitFeedback
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeedbackDto'
            example:
              name: Avery Developer
              company: Example Energy Co
              feedback_type: docs_issue
              summary: Clarify the usage array shape for period bill impact
              message: >-
                The period bill impact docs could state explicitly that each
                daily usage array needs 96 fifteen-minute values.
              page: /api-reference/endpoint/homes/calculate-period-bill-impact
              endpoint: /v1/homes/{id}/calculate/impact
              environment: sandbox
              submitter:
                kind: agent
                agent: claude-code
                client: cli
              contact:
                email: developer@example.com
                preferred_contact: email
                consent_to_contact: true
      responses:
        '201':
          description: Feedback received
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackResponseDto'
              example:
                feedback_id: ws_feedback_123456789
                received: true
                follow_up:
                  requested: true
                  contact_method: email
        '400':
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelopeDto'
        '429':
          description: Too many feedback submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelopeDto'
components:
  schemas:
    CreateFeedbackDto:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        company:
          type: string
          maxLength: 255
        message:
          type: string
          maxLength: 4000
        page:
          type: string
          maxLength: 2048
        feedback_type:
          type: string
          enum:
            - question
            - docs_issue
            - source_of_truth_disagreement
            - blocked_build
            - bug
            - feature_request
            - integration_request
            - suggestion
            - other
          default: other
        summary:
          type: string
          maxLength: 500
        question:
          type: string
          maxLength: 4000
        expected_behavior:
          type: string
          maxLength: 4000
        actual_behavior:
          type: string
          maxLength: 4000
        sanitized_evidence: {}
        error: {}
        repro_steps:
          type: string
          maxLength: 4000
        suggested_fix:
          type: string
          maxLength: 4000
        endpoint:
          type: string
          maxLength: 255
        operation_id:
          type: string
          maxLength: 255
        environment:
          type: string
          maxLength: 64
        request_id:
          type: string
          maxLength: 128
        docs_url:
          type: string
          format: uri
        source_urls:
          type: array
          maxItems: 10
          items:
            type: string
            format: uri
          default: []
        routing_tags:
          type: object
          properties:
            endpoint:
              type: string
            operation_id:
              type: string
            environment:
              type: string
            request_id:
              type: string
            utility_name:
              type: string
            utility_eia_id:
              type: string
            zip_code:
              type: string
            rate_plan_id:
              type: string
            tariff_id:
              type: string
            source:
              type: string
        inferred_owning_area:
          type: string
          maxLength: 128
        submitter:
          type: object
          properties:
            kind:
              type: string
              enum:
                - human
                - agent
                - system
            agent:
              type: string
              maxLength: 128
            client:
              type: string
              maxLength: 128
        contact:
          type: object
          properties:
            email:
              type: string
              format: email
            preferred_contact:
              type: string
              enum:
                - email
            consent_to_contact:
              type: boolean
              default: false
            notes:
              type: string
              maxLength: 2000
    FeedbackResponseDto:
      type: object
      properties:
        feedback_id:
          type: string
        received:
          type: boolean
        follow_up:
          type: object
          properties:
            requested:
              type: boolean
            contact_method:
              type: string
          required:
            - requested
      required:
        - feedback_id
        - received
        - follow_up
    ApiErrorEnvelopeDto:
      type: object
      properties:
        request_id:
          type: string
          example: req_123
        error_code:
          type: string
          enum:
            - AUTH_MISSING_API_KEY
            - AUTH_INVALID_API_KEY
            - AUTH_EXPIRED_CREDENTIAL
            - AUTH_REVOKED_CREDENTIAL
            - AUTH_INSUFFICIENT_SCOPE
            - VALIDATION_FAILED
            - RATE_LIMITED
            - NOT_FOUND
            - FORBIDDEN
            - PRODUCTION_ACCESS_DENIED
            - INTERNAL_ERROR
          example: VALIDATION_FAILED
        message:
          type: string
          example: Request validation failed.
        recovery_action:
          type: string
          example: >-
            Provide the x-ws-api-key header. If this contradicts the public
            docs, submit feedback through /v1/feedback.
        field_errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiFieldErrorDto'
        retry_after_seconds:
          type: number
          example: 3600
      required:
        - request_id
        - error_code
        - message
    ApiFieldErrorDto:
      type: object
      properties:
        field:
          type: string
          example: zipcode
        message:
          type: string
          example: zipcode is invalid
      required:
        - message

````