openapi.yaml

openapi: 3.1.0
info:
  title: HollerKit Report API
  version: 0.5.0
  description: |
    Machine-readable contract for receiving signed HollerKit bug reports.

    The report endpoint accepts `multipart/form-data`. JSON payloads such as
    `metadata`, `breadcrumbs`, and `transcript` are sent as multipart text fields
    containing JSON strings.
servers:
  - url: https://example.com
    description: Replace with your HollerKit backend origin.
paths:
  /bug-report:
    post:
      operationId: createBugReport
      summary: Create a signed bug report
      description: |
        Accepts a timestamped HMAC-signed multipart report and creates, skips,
        or dispatches the report according to the server configuration.

        The signature is the lowercase hex HMAC-SHA256 of `body || timestamp`
        using the configured app secret.
      security:
        - HollerKitTimestamp: []
          HollerKitSignature: []
      parameters:
        - $ref: '#/components/parameters/ContentLength'
        - $ref: '#/components/parameters/HollerKitTimestamp'
        - $ref: '#/components/parameters/HollerKitSignature'
        - $ref: '#/components/parameters/HollerKitRequestId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BugReportMultipartRequest'
            encoding:
              image:
                contentType: image/png, image/jpeg, image/heic, image/heif
              audio:
                contentType: audio/mp4, audio/aac, audio/m4a, audio/x-m4a
      responses:
        '200':
          description: The report was accepted.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BugReportCreatedResponse'
                  - $ref: '#/components/schemas/BugReportSkippedResponse'
              examples:
                created:
                  value:
                    ok: true
                    issueUrl: https://github.com/owner/repo/issues/1
                    reportId: 018f2d0c-33d8-7d6a-b0e2-7fb4cf957e99
                skipped:
                  value:
                    ok: true
                    reportId: 018f2d0c-33d8-7d6a-b0e2-7fb4cf957e99
                    skipped: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    HollerKitTimestamp:
      type: apiKey
      in: header
      name: x-hollerkit-timestamp
      description: Unix seconds timestamp covered by the HMAC signature.
    HollerKitSignature:
      type: apiKey
      in: header
      name: x-hollerkit-signature
      description: Lowercase hex HMAC-SHA256 of `body || timestamp`.
  parameters:
    ContentLength:
      name: Content-Length
      in: header
      required: false
      description: Request body byte count. Servers reject values above `maxBodyBytes` before buffering.
      schema:
        type: integer
        minimum: 0
      example: 12452
    HollerKitTimestamp:
      name: x-hollerkit-timestamp
      in: header
      required: true
      description: Unix seconds timestamp covered by the HMAC signature.
      schema:
        type: integer
        minimum: 1
      example: 1777857600
    HollerKitSignature:
      name: x-hollerkit-signature
      in: header
      required: true
      description: Lowercase hex HMAC-SHA256 of `body || timestamp`.
      schema:
        type: string
        pattern: '^[a-f0-9]{64}$'
      example: b35166f39a9ce2767342b3153007692e1de6b1c68394e4abb57f806dc23486bd
    HollerKitRequestId:
      name: x-hollerkit-request-id
      in: header
      required: false
      description: Optional deployment extension for replay deduplication. Include it in the signed material if used.
      schema:
        type: string
        minLength: 1
        maxLength: 200
  responses:
    BadRequest:
      description: The request is malformed or violates report mode rules.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidInputMode:
              value:
                ok: false
                error:
                  code: invalid_input_mode
                  message: Invalid inputMode value.
    Unauthorized:
      description: The request is missing or fails authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidSignature:
              value:
                ok: false
                error:
                  code: invalid_signature
                  message: Invalid HollerKit request signature.
    MethodNotAllowed:
      description: The endpoint only accepts POST.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: The report exceeds a configured count, byte, duration, or length limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: The request or an uploaded file uses an unsupported media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: The server failed to handle the report.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    BugReportMultipartRequest:
      type: object
      properties:
        inputMode:
          $ref: '#/components/schemas/InputMode'
        comment:
          type: string
          description: Optional typed report comment. Not allowed for `audio-only` reports.
          maxLength: 10000
        transcript:
          type: string
          description: JSON string matching `TranscriptPayload`.
          contentMediaType: application/json
          contentSchema:
            $ref: '#/components/schemas/TranscriptPayload'
          examples:
            - '{"text":"It crashes after I tap save.","locale":"en-US","engine":"apple-on-device","durationSeconds":12}'
        metadata:
          type: string
          description: JSON object string containing app, device, OS, and integration metadata.
          contentMediaType: application/json
          contentSchema:
            type: object
            additionalProperties: true
          examples:
            - '{"appVersion":"1.0","osVersion":"iOS 18.5"}'
        breadcrumbs:
          type: string
          description: JSON array string of recent app events.
          contentMediaType: application/json
          contentSchema:
            type: array
            maxItems: 100
            items:
              $ref: '#/components/schemas/Breadcrumb'
          examples:
            - '[{"timestamp":"2026-05-03T20:00:00.000Z","category":"checkout","message":"Tapped pay"}]'
        userIdHash:
          type: string
          description: Optional opaque hashed user identifier.
        image:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/ImageFile'
          description: Repeatable image file field.
        audio:
          $ref: '#/components/schemas/AudioFile'
      additionalProperties: false
      anyOf:
        - required: [comment]
        - required: [transcript]
        - required: [image]
        - required: [audio]
    InputMode:
      type: string
      default: text-and-audio
      enum:
        - text-and-audio
        - text-only
        - audio-only
    ImageFile:
      type: string
      format: binary
      description: PNG, JPEG, HEIC, or HEIF image file. Default limit is 8 MB per image.
    AudioFile:
      type: string
      format: binary
      description: M4A/AAC-style short audio note. Default limits are one file, 2 MB, and 60 seconds.
    TranscriptPayload:
      type: object
      required:
        - text
        - locale
        - engine
      properties:
        text:
          type: string
          maxLength: 20000
        locale:
          type: string
          examples: [en-US]
        engine:
          type: string
          enum:
            - apple-on-device
            - apple-network
            - manual
            - unavailable
        confidence:
          type: number
          minimum: 0
          maximum: 1
        durationSeconds:
          type: number
          minimum: 0
          maximum: 60
      additionalProperties: true
    Breadcrumb:
      type: object
      required:
        - message
      properties:
        timestamp:
          type: string
          format: date-time
        category:
          type: string
        message:
          type: string
        metadata:
          type: object
          additionalProperties: true
      additionalProperties: true
    BugReportCreatedResponse:
      type: object
      required:
        - ok
        - issueUrl
        - reportId
      properties:
        ok:
          type: boolean
          const: true
        issueUrl:
          type: string
          format: uri
        reportId:
          type: string
    BugReportSkippedResponse:
      type: object
      required:
        - ok
        - reportId
        - skipped
      properties:
        ok:
          type: boolean
          const: true
        reportId:
          type: string
        skipped:
          type: boolean
          const: true
    ErrorResponse:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
    ErrorCode:
      type: string
      enum:
        - audio_not_allowed
        - audio_too_large
        - audio_too_long
        - body_too_large
        - comment_not_allowed
        - comment_too_large
        - empty_report
        - image_too_large
        - internal_error
        - invalid_breadcrumbs
        - invalid_content_length
        - invalid_field
        - invalid_file
        - invalid_input_mode
        - invalid_json
        - invalid_signature
        - invalid_timestamp
        - invalid_transcript
        - metadata_too_large
        - method_not_allowed
        - missing_signature
        - missing_storage_adapter
        - missing_timestamp
        - timestamp_out_of_range
        - too_many_audio_files
        - too_many_breadcrumbs
        - too_many_images
        - transcript_too_large
        - unsupported_audio_type
        - unsupported_content_type
        - unsupported_image_type