openapi: 3.1.0
info:
  title: Feedback Portal API
  version: 1.0.0
  description: Submit product feedback to a project using a server-side API key.
servers:
  - url: http://localhost:3200
    description: Local development
paths:
  /v1/feedback:
    post:
      operationId: createFeedback
      summary: Submit one feedback item
      description: >-
        The project and Test/Live mode are derived from the bearer key. This API
        is write-only. Per-key request limits are configured by the operator;
        clients must follow Retry-After when a request receives 429.
      security:
        - bearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            A caller-generated key scoped to the project. Reuse the same key
            and payload when retrying an uncertain request. Idempotency is kept
            for 24 hours.
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
            examples:
              idea:
                value:
                  type: idea
                  message: The export takes a long time.
                  title: Slow export
                  submitter:
                    name: Example User
                    email: user@example.invalid
                  context:
                    version: 2.4
                    platform: web
              bug:
                value:
                  type: issue
                  message: The application displays an error after saving a profile.
                  title: Profile save returns an error
                  bugDetails:
                    stepsToReproduce: Open Settings, change the display name, and select Save.
                    expectedResult: The new display name appears in the profile.
                    actualResult: An error appears after saving, although the new name is shown.
                    environment: Chrome 126 on macOS
                    version: 2.4.1
      responses:
        '201':
          description: Feedback was persisted or the original idempotent result was returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackCreated'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
        '429':
          description: The API key exceeded its configured per-key limit. Retry after the supplied delay.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          $ref: '#/components/responses/Problem'
  /v1/widget/tokens:
    post:
      operationId: createWidgetToken
      summary: Issue a short-lived hosted-widget token
      description: >-
        Call this endpoint from the customer's server-side token proxy. The
        customer's long-lived project key MUST NOT be sent to browser code.
        The supplied page origin MUST be on the project's exact-origin
        allowlist. Token issuance is not service-rate-limited; customers MUST
        rate-limit their own public token proxy.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetTokenRequest'
            example:
              origin: https://app.example.com
              user:
                id: customer-123
                name: Example User
                email: user@example.invalid
      responses:
        '201':
          description: A one-feedback token valid for 15 minutes was issued.
          headers:
            Cache-Control:
              required: true
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetTokenResponse'
        '401':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
        '500':
          $ref: '#/components/responses/Problem'
    options:
      operationId: preflightWidgetToken
      summary: Check browser access for widget token CORS
      parameters:
        - $ref: '#/components/parameters/Origin'
      responses:
        '204':
          $ref: '#/components/responses/WidgetPreflight'
        '403':
          $ref: '#/components/responses/Problem'
        '500':
          $ref: '#/components/responses/Problem'
  /v1/widget/feedback:
    post:
      operationId: createWidgetFeedback
      summary: Submit feedback using a one-feedback widget token
      description: >-
        The browser sends the temporary token in the JSON body and the
        Idempotency-Key in a request header. The token is bound to the exact
        Origin, project, mode, issuing key, and customer user claims. Feedback
        submissions use the existing per-key API_RATE_LIMIT_PER_MINUTE policy.
      parameters:
        - $ref: '#/components/parameters/Origin'
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Reuse the same key with an unchanged payload for an uncertain retry.
            Idempotency records are retained for 24 hours.
          schema:
            type: string
            minLength: 1
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetFeedbackRequest'
            example:
              token: opaque-short-lived-token
              type: idea
              message: The export takes a long time.
              context:
                widgetPagePath: /reports
                platform: web
      responses:
        '201':
          description: Feedback was persisted or the idempotent result was returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackCreated'
        '401':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
        '429':
          description: The API key exceeded its configured per-key limit.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          $ref: '#/components/responses/Problem'
    options:
      operationId: preflightWidgetFeedback
      summary: Check browser access for widget feedback CORS
      parameters:
        - $ref: '#/components/parameters/Origin'
      responses:
        '204':
          $ref: '#/components/responses/WidgetPreflight'
        '403':
          $ref: '#/components/responses/Problem'
        '500':
          $ref: '#/components/responses/Problem'
components:
  parameters:
    Origin:
      name: Origin
      in: header
      required: true
      description: The exact browser page origin; reflected only for configured widget origins.
      schema:
        type: string
        format: uri
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Project-scoped test or live API key. Keys are accepted only in this header, never in a URL.
  responses:
    WidgetPreflight:
      description: CORS preflight accepted for an allowlisted origin; credentials are not enabled.
      headers:
        Access-Control-Allow-Origin:
          schema:
            type: string
        Access-Control-Allow-Methods:
          schema:
            type: string
            const: POST, OPTIONS
        Access-Control-Allow-Headers:
          schema:
            type: string
        Access-Control-Expose-Headers:
          schema:
            type: string
            const: Retry-After
        Vary:
          schema:
            type: string
            const: Origin
    Problem:
      description: RFC 9457 Problem Details response.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  schemas:
    WidgetTokenRequest:
      type: object
      additionalProperties: false
      required: [origin]
      properties:
        origin:
          type: string
          format: uri
          description: Exact page origin derived by the customer's backend from its browser request.
        user:
          type: object
          additionalProperties: false
          properties:
            id:
              type: string
            name:
              type: string
            email:
              type: string
              format: email
    WidgetTokenResponse:
      type: object
      additionalProperties: false
      required: [token, expiresAt]
      properties:
        token:
          type: string
          description: Opaque one-feedback token. Store only in browser memory.
        expiresAt:
          type: string
          format: date-time
    WidgetFeedbackRequest:
      type: object
      additionalProperties: false
      required: [token, type, message]
      properties:
        token:
          type: string
          minLength: 1
        type:
          type: string
          enum: [idea, issue, general]
        message:
          type: string
          minLength: 1
          maxLength: 10000
        title:
          type: string
          maxLength: 200
        submitter:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            email:
              type: string
              format: email
        context:
          type: object
          maxProperties: 20
          description: >-
            Flat metadata map, at most 8 KB as JSON. The hosted asset reserves
            widget and customer-user keys from data-context; final context may
            contain automatic widget keys. Customer-user claims come from the token.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
        bugDetails:
          $ref: '#/components/schemas/BugDetails'
      allOf:
        - if:
            properties:
              type:
                const: issue
            required: [type]
          then: {}
          else:
            not:
              required: [bugDetails]
    FeedbackRequest:
      type: object
      additionalProperties: false
      required: [type, message]
      properties:
        type:
          type: string
          enum: [idea, issue, general]
        message:
          type: string
          minLength: 1
          maxLength: 10000
        title:
          type: string
          maxLength: 200
        submitter:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            email:
              type: string
              format: email
        context:
          type: object
          maxProperties: 20
          description: Flat metadata map, at most 8 KB when JSON encoded.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
        bugDetails:
          $ref: '#/components/schemas/BugDetails'
      allOf:
        - if:
            properties:
              type:
                const: issue
            required: [type]
          then: {}
          else:
            not:
              required: [bugDetails]
    BugDetails:
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        stepsToReproduce:
          type: string
          maxLength: 10000
          pattern: '\S'
        expectedResult:
          type: string
          maxLength: 10000
          pattern: '\S'
        actualResult:
          type: string
          maxLength: 10000
          pattern: '\S'
        environment:
          type: string
          maxLength: 200
          pattern: '\S'
        version:
          type: string
          maxLength: 200
          pattern: '\S'
    FeedbackCreated:
      type: object
      additionalProperties: false
      required: [id, createdAt, type, status]
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        type:
          type: string
          enum: [idea, issue, general]
        status:
          type: string
          const: new
    ProblemDetails:
      type: object
      additionalProperties: true
      required: [type, title, status, detail, instance]
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
