DPF Account API

openapi: 3.2.0
info:
  title: DPF Account API
  version: 1.1.0
  description: '## Common error responses


    Unless otherwise noted, any authenticated endpoint may also return the following

    responses, each with the standard `ErrorResponse` body. To avoid repetition they are

    not listed individually on each operation:


    - **400 Bad Request** — malformed JSON, unknown action, or missing/invalid fields

    - **401 Unauthorized** — missing or invalid JWT bearer token

    - **402 Payment Required** — the account has insufficient credits or an inactive subscription

    - **403 Forbidden** — authenticated but not permitted (no access to the resource, or a higher access level / plan tier is required)


    Operation-specific responses (e.g. `404`, `409`) are documented on each endpoint.'
  contact:
    name: Contact DPF
    url: mailto:contact@dpf-it.com
  license:
    name: Proprietary
    url: https://dpf-it.com/#terms
servers:
- url: https://api.dpf-it.com
  description: Production API
security: []
tags:
- name: Account
  description: Account management endpoints (password reset, etc.)
paths:
  /auth/request-password-reset:
    post:
      tags:
      - Account
      summary: Request password reset
      description: Request a password reset. OTP will be sent to user email
      operationId: requestPasswordReset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestPasswordResetRequest'
      responses:
        '200':
          description: Password reset requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestPasswordResetResponse'
  /auth/reset-password:
    post:
      tags:
      - Account
      summary: Reset password
      description: Reset user password using OTP from email
      operationId: resetPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
      responses:
        '200':
          description: Password reset successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResetPasswordResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/settings:
    get:
      tags:
      - Account
      summary: Get user settings
      description: Returns the authenticated user's profile and preferences (name, auto top-off).
      operationId: getSettings
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSettingsResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Account
      summary: Update user settings
      description: 'Updates the authenticated user''s profile and preferences. Any combination of

        `firstName`, `lastName`, and `topOffEnabled` may be provided; only the fields

        present in the request body are changed.'
      operationId: updateSettings
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSettingsRequest'
      responses:
        '200':
          description: Settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSettingsResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/notification-preferences:
    get:
      tags:
      - Account
      summary: List notification preferences
      description: 'Returns the notification message-type registry (each type''s label, category,

        eligible roles, and which roles receive it by default) plus the authenticated

        user''s explicit preference overrides. A `(workspace, messageType)` with no

        override row follows the type''s default.'
      operationId: listNotificationPreferences
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Preferences retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotificationPreferencesResponse'
    put:
      tags:
      - Account
      summary: Set a notification preference
      description: 'Upserts a single notification preference override for the authenticated user,

        scoped to a workspace and message type. Eligibility (e.g. billing types are

        owner-only) is enforced at send time, so storing an override that a hard gate

        later ignores is harmless.'
      operationId: setNotificationPreference
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetNotificationPreferenceRequest'
      responses:
        '200':
          description: Preference saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferenceResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Account
      summary: Reset a notification preference
      description: 'Removes a single preference override, reverting the `(workspace, messageType)`

        back to its default. `workspaceId` and `messageType` may be supplied in the JSON

        body or as query-string parameters.'
      operationId: deleteNotificationPreference
      security:
      - BearerAuth: []
      parameters:
      - name: workspaceId
        in: query
        required: false
        schema:
          type: string
      - name: messageType
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Preference reset successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/billing:
    post:
      tags:
      - Account
      summary: Billing & credit management
      description: 'Multi-action billing endpoint. The `action` field determines the operation.

        All actions require JWT authentication.


        **Actions:**


        - **get-balance** (default): Returns credit balance for the current billing month of the authenticated user.

        - If `workspaceId` is provided, returns the balance of that workspace''s owner instead.

        - Triggers auto top-off via Stripe if balance < 100 credits, the owner has `topOffEnabled`, a paid tier, and a saved payment method.


        - **purchase-credits**: Creates a one-time credit purchase on the authenticated user''s own account.

        - If the user has a saved payment method, charges immediately (off-session) and credits are added via webhook.

        - If not, returns a Stripe Checkout URL to complete payment.

        - A Stripe customer is created lazily if one does not already exist.


        - **modify-subscription**: Changes the authenticated user''s subscription tier.

        - If the user has a payment method: upgrades/downgrades directly via API.

        - If the user needs to add a payment method (upgrade with no card on file): returns a Stripe Checkout URL.

        - Upgrades prorate immediately. Downgrades apply at the next billing cycle.


        - **manage-payment**: Returns a Stripe Customer Portal URL where the authenticated user can manage payment methods.

        - Always returns a URL (user is redirected to Stripe).'
      operationId: billing
      security:
      - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/GetBalanceRequest'
              - $ref: '#/components/schemas/PurchaseCreditsRequest'
              - $ref: '#/components/schemas/ModifySubscriptionRequest'
              - $ref: '#/components/schemas/ManagePaymentRequest'
              - $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '200':
          description: Action completed successfully
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GetBalanceResponse'
                - $ref: '#/components/schemas/PurchaseCreditsResponse'
                - $ref: '#/components/schemas/ModifySubscriptionResponse'
                - $ref: '#/components/schemas/ManagePaymentResponse'
                - $ref: '#/components/schemas/CreateCustomerResponse'
        '404':
          description: Workspace or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GetBalanceResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            credits:
              type: number
              description: Current credit balance (can be negative)
              example: 742.5
            tier:
              type: string
              enum:
              - free
              - starter
              - pro
              description: User's current pricing tier
              example: starter
            creditsPurchased:
              type: number
              description: Total credits allocated at start of billing month
              example: 1000
            creditsConsumed:
              type: number
              description: Total credits consumed this month (absolute value)
              example: 257.5
            topOffCount:
              type: integer
              description: Number of auto top-offs this month
              example: 0
            autoTopOffCredits:
              type: number
              description: Total credits added via auto top-off this month
              example: 0
            month:
              type: string
              description: Billing month (YYYY-MM format)
              example: 2026-06
            hasPaymentMethod:
              type: boolean
              description: Whether the user has a saved Stripe payment method on file
              example: true
            renewsOn:
              type: string
              description: Date the current billing period renews (YYYY-MM-DD). Omitted if no billing dates are known yet.
              example: '2026-07-01'
            ownerUserId:
              type: string
              description: User ID of the workspace owner (only present when workspaceId was provided)
              example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            topOffTriggered:
              type: boolean
              description: Present and true if an auto top-off was triggered during this request
              example: true
    GetSettingsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            firstName:
              type: string
              example: Jane
            lastName:
              type: string
              example: Doe
            topOffEnabled:
              type: boolean
              description: Whether auto top-off (automatic credit purchase when balance is low) is active
              example: false
    SetNotificationPreferenceRequest:
      type: object
      required:
      - workspaceId
      - messageType
      - enabled
      properties:
        workspaceId:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        messageType:
          type: string
          description: Must be a known notification message type.
          example: job.succeeded
        enabled:
          type: boolean
          example: true
        channels:
          type: array
          description: Optional. Defaults to ["email"].
          items:
            type: string
          example:
          - email
    CreateCustomerResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            stripeCustomerId:
              type: string
              description: The user's Stripe customer ID (newly created or pre-existing)
              example: cus_QabC1dEf2GhIjK
            alreadyExists:
              type: boolean
              description: True if a Stripe customer already existed (HTTP 200); false if one was created (HTTP 201)
              example: false
    PurchaseCreditsRequest:
      type: object
      required:
      - action
      properties:
        action:
          type: string
          enum:
          - purchase-credits
        creditAmount:
          type: integer
          minimum: 100
          description: Number of credits to purchase. Must be an integer ≥ 100. Defaults to 100 if omitted.
          example: 100
    UpdateSettingsRequest:
      type: object
      description: At least one field should be provided.
      properties:
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Doe
        topOffEnabled:
          type: boolean
          example: true
    NotificationPreference:
      type: object
      properties:
        workspaceId:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        messageType:
          type: string
          example: job.succeeded
        enabled:
          type: boolean
          example: true
        channels:
          type: array
          items:
            type: string
          example:
          - email
        updatedAt:
          type: string
          format: date-time
          example: '2026-07-05T00:00:00.000Z'
    NotificationType:
      type: object
      description: A notification message type and how it is delivered by role.
      properties:
        messageType:
          type: string
          example: job.failed
        label:
          type: string
          example: Job failed
        category:
          type: string
          enum:
          - operational
          - billing
          example: operational
        eligible:
          type: array
          description: Roles that may ever receive this type (hard gate).
          items:
            type: string
            enum:
            - owner
            - full
            - read-only
          example:
          - owner
          - full
          - read-only
        defaultOn:
          type: array
          description: Roles that receive this type with no explicit preference.
          items:
            type: string
            enum:
            - owner
            - full
            - read-only
          example:
          - owner
          - full
    ResetPasswordRequest:
      type: object
      required:
      - email
      - otp
      - newPassword
      properties:
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
        otp:
          type: string
          description: One-time password from email (6 digits)
          example: '123456'
          pattern: ^\d{6}$
        newPassword:
          type: string
          description: New password (min 8 chars, max 128 chars)
          example: NewPassword456
          minLength: 8
          maxLength: 128
    ModifySubscriptionResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            message:
              type: string
              description: Human-readable result message
              example: Upgraded to pro. Pro-rated credits have been added.
            url:
              type: string
              description: Present if the user needs to add a payment method to complete an upgrade — a Stripe Checkout URL
              example: https://checkout.stripe.com/c/pay/...
            newTier:
              type: string
              enum:
              - free
              - starter
              - pro
            isUpgrade:
              type: boolean
              description: Whether the change was an upgrade (true) or downgrade (false)
    ListNotificationPreferencesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            types:
              type: array
              items:
                $ref: '#/components/schemas/NotificationType'
            preferences:
              type: array
              items:
                $ref: '#/components/schemas/NotificationPreference'
    GetBalanceRequest:
      type: object
      properties:
        action:
          type: string
          enum:
          - get-balance
          description: Action identifier (optional, defaults to get-balance)
        workspaceId:
          type: string
          description: Optional workspace ID. When provided, returns the workspace owner's balance.
    ModifySubscriptionRequest:
      type: object
      required:
      - action
      - newTier
      properties:
        action:
          type: string
          enum:
          - modify-subscription
        newTier:
          type: string
          enum:
          - free
          - starter
          - pro
          description: Target subscription tier
        couponCode:
          type: string
          description: Optional Stripe promotion code to apply to the subscription change.
          example: LAUNCH20
    RequestPasswordResetRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
    ResetPasswordResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            message:
              type: string
              example: Password has been reset successfully.
    ManagePaymentRequest:
      type: object
      required:
      - action
      properties:
        action:
          type: string
          enum:
          - manage-payment
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: INVALID_EMAIL
            message:
              type: string
              description: Human-readable error message
              example: Invalid email format
    NotificationPreferenceResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/NotificationPreference'
    ManagePaymentResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            url:
              type: string
              description: Stripe Customer Portal URL for managing payment methods
              example: https://billing.stripe.com/p/session/...
    CreateCustomerRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    RequestPasswordResetResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            message:
              type: string
              example: If an account exists with this email, you will receive a password reset link.
    PurchaseCreditsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            message:
              type: string
              description: Present if payment was charged off-session (saved payment method)
              example: Credits purchased. They will appear shortly.
            url:
              type: string
              description: Present if user needs to complete payment via Stripe Checkout
              example: https://checkout.stripe.com/c/pay/...
            creditAmount:
              type: integer
              example: 100
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login or registration