openapi.yaml

openapi: 3.1.0
info:
  title: Wealthboard API
  version: 1.0.0
  license:
    name: MIT
    identifier: MIT
servers:
  - url: /api/v1
paths:
  /auth/config:
    get:
      operationId: getAuthConfig
      summary: Return enabled browser authentication methods
      security: []
      responses:
        "200":
          description: Authentication capabilities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthConfig"
  /overview:
    get:
      operationId: getOverview
      summary: Return the current user's read-only overview
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped account overview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Overview"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /categories:
    get:
      operationId: listCategories
      summary: List the current user's account categories
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped categories
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Category"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createCategory
      summary: Create an account category
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CategoryMutationRequest"
      responses:
        "201":
          description: Category created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Category"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /categories/{id}:
    put:
      operationId: updateCategory
      summary: Replace an account category
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CategoryMutationRequest"
      responses:
        "200":
          description: Category updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /categories/{id}/archive:
    patch:
      operationId: setCategoryArchived
      summary: Archive or restore an account category
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. An omitted `archived` value restores the category.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveMutationRequest"
      responses:
        "200":
          description: Category archive state updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /categories/{id}/reorder:
    post:
      operationId: reorderCategory
      summary: Move an account category one position
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CategoryReorderRequest"
      responses:
        "200":
          description: Category order updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /institutions:
    get:
      operationId: listInstitutions
      summary: List the current user's institutions
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped institutions
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Institution"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createInstitution
      summary: Create a financial institution
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstitutionMutationRequest"
      responses:
        "201":
          description: Institution created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Institution"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /institutions/{id}:
    put:
      operationId: updateInstitution
      summary: Replace a financial institution
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstitutionMutationRequest"
      responses:
        "200":
          description: Institution updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /institutions/{id}/archive:
    patch:
      operationId: setInstitutionArchived
      summary: Archive or restore a financial institution
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. An omitted `archived` value restores the institution.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveMutationRequest"
      responses:
        "200":
          description: Institution archive state updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /exchange-rates:
    post:
      operationId: createExchangeRate
      summary: Create a dated manual exchange rate
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Rates are exact positive decimal strings.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExchangeRateMutationRequest"
      responses:
        "201":
          description: Exchange rate created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExchangeRate"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /exchange-rates/{id}:
    delete:
      operationId: deleteExchangeRate
      summary: Delete a manual exchange rate
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Exchange rate deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts:
    get:
      operationId: listAccounts
      summary: List the current user's accounts
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ArchivedFilter"
      responses:
        "200":
          description: Owner-scoped accounts
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Account"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createAccount
      summary: Create an account and opening balance
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Monetary values are integer minor-unit strings; idempotency is supplied in the JSON body.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountCreateRequest"
      responses:
        "201":
          description: Account created or an identical request replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}:
    get:
      operationId: getAccount
      summary: Return one account owned by the current user
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        "200":
          description: Owner-scoped account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    patch:
      operationId: updateAccount
      summary: Update an account
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Currency and tracking mode cannot change after creation.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountUpdateRequest"
      responses:
        "204": { description: Account updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deleteAccount
      summary: Permanently delete an archived account
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountDeleteRequest"
      responses:
        "204": { description: Account deleted }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/archive:
    post:
      operationId: setAccountArchived
      summary: Archive or restore an account
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequiredArchiveMutationRequest"
      responses:
        "204": { description: Account archive state updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/transactions:
    get:
      operationId: listAccountTransactions
      summary: List transactions for one account
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/TransactionType"
        - $ref: "#/components/parameters/FromDate"
        - $ref: "#/components/parameters/ToDate"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Page of owner-scoped account transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionPage"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
  /accounts/{accountID}/valuations:
    get:
      operationId: listAccountValuations
      summary: List valuation snapshots for one account
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/FromDate"
        - $ref: "#/components/parameters/ToDate"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Page of owner-scoped account valuations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValuationPage"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
  /accounts/{accountID}/activity:
    get:
      operationId: listAccountActivity
      summary: List combined transaction and valuation activity for one account
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/FromDate"
        - $ref: "#/components/parameters/ToDate"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Page of owner-scoped account activity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityPage"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
  /accounts/{accountID}/position-events:
    get:
      operationId: listAccountPositionEvents
      summary: List position events for one account
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Page of owner-scoped account position events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PositionEventPage"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/position-events/{id}:
    get:
      operationId: getAccountPositionEvent
      summary: Read one position event for correction
      description: Requires portfolio:read. Both the account and event must belong to the authenticated user.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200":
          description: Owner-scoped account position event
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PositionEvent"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/position-reconciliations:
    get:
      operationId: listAccountPositionReconciliations
      summary: List position reconciliations for one account
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Page of owner-scoped account position reconciliations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PositionReconciliationPage"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /transactions:
    get:
      operationId: listTransactions
      summary: List the current user's transactions
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountIDFilter"
        - $ref: "#/components/parameters/TransactionType"
        - $ref: "#/components/parameters/FromDate"
        - $ref: "#/components/parameters/ToDate"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Page of owner-scoped transactions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionPage"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createTransaction
      summary: Create a ledger transaction
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Amounts are integer minor-unit strings; idempotency is supplied in the JSON body.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionCreateRequest"
      responses:
        "201":
          description: Transaction created or an identical request replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /transactions/{id}:
    patch:
      operationId: updateTransaction
      summary: Update a ledger transaction
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Opening balances, transfers, and grouped investment activity cannot be edited here.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionUpdateRequest"
      responses:
        "204": { description: Transaction updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deleteTransaction
      summary: Delete a ledger transaction or paired transfer
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Transaction or transfer pair deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /valuations:
    post:
      operationId: createValuation
      summary: Create an absolute account valuation
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Values are non-negative integer minor-unit strings; idempotency is supplied in the JSON body.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValuationCreateRequest"
      responses:
        "201":
          description: Valuation created or an identical request replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /valuations/{id}:
    delete:
      operationId: deleteValuation
      summary: Delete an account valuation
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Valuation deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /transfers:
    post:
      operationId: createTransfer
      summary: Create an atomic paired-account transfer
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Amounts are integer minor-unit strings; omit `destinationAmountMinor` to derive it from currency and dated rates.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransferCreateRequest"
      responses:
        "201":
          description: Transfer created or an identical request replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals:
    get:
      operationId: listGoals
      summary: List the current user's goals
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped goals
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Goal"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createGoal
      summary: Create a financial goal and contribution plan
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Monetary inputs are major-unit decimal strings. Idempotency may be supplied in the body or `Idempotency-Key`; when both are present they must match.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalMutationRequest"
      responses:
        "200":
          description: An idempotent goal creation was replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalMutationResult"
        "201":
          description: Goal created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GoalMutationResult"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/{id}:
    get:
      operationId: getGoal
      summary: Return one goal owned by the current user
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200":
          description: Owner-scoped goal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Goal"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    put:
      operationId: updateGoal
      summary: Replace a financial goal and contribution plan
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Any body idempotency key is ignored.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalMutationRequest"
      responses:
        "200":
          description: Goal updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deleteGoal
      summary: Delete a financial goal
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Goal deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/{id}/scenarios:
    get:
      operationId: calculateGoalScenarios
      summary: Calculate temporary goal scenarios
      description: Calculates owner-scoped comparison scenarios without saving them. Requires `portfolio:read`; contribution values use integer minor units.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - name: monthlyContributionMinor
          in: query
          required: true
          schema: { $ref: "#/components/schemas/MinorUnits" }
        - name: annualReturnBps
          in: query
          required: true
          schema: { type: integer, format: int32, minimum: 0, maximum: 10000 }
      responses:
        "200":
          description: Temporary saved-plan, required-pace, and lower-return scenarios
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GoalScenarios" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/{id}/status:
    patch:
      operationId: setGoalStatus
      summary: Set a financial goal status
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalStatusRequest"
      responses:
        "200":
          description: Goal status updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/{id}/milestones:
    get:
      operationId: listGoalMilestones
      summary: List milestones for one goal
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200":
          description: Owner-scoped goal milestones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GoalMilestone"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createGoalMilestone
      summary: Create a milestone for a financial goal
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The target amount is a major-unit decimal string in the goal currency.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GoalMilestoneCreateRequest"
      responses:
        "201":
          description: Goal milestone created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/{id}/milestones/{milestoneId}:
    delete:
      operationId: deleteGoalMilestone
      summary: Delete a milestone from a financial goal
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - name: milestoneId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Goal milestone deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/{id}/alerts/dismiss:
    post:
      operationId: dismissGoalAlert
      summary: Dismiss the current monthly alert for a goal
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "200":
          description: Goal alert dismissed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /goals/alerts:
    get:
      operationId: listGoalAlerts
      summary: List active alerts for the current user's goals
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped goal alerts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GoalAlert"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /dashboard:
    get:
      operationId: getDashboard
      summary: Return the current dashboard snapshot
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - name: range
          in: query
          schema:
            type: string
            enum: [1m, 3m, 6m, 1y, all]
            default: 1y
      responses:
        "200":
          description: Owner-scoped dashboard snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dashboard"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /accounts/{accountID}/analytics:
    get:
      operationId: getAccountAnalytics
      summary: Return replayed value history for an owner-scoped account
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        "200":
          description: Owner-scoped account analytics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountAnalytics"
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
  /reports/summary:
    get:
      operationId: getReportSummary
      summary: Return the current portfolio summary report
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped portfolio summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportSummary"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /reports/allocation:
    get:
      operationId: getReportAllocation
      summary: Return current portfolio allocation breakdowns
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped allocation report
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportAllocation"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /settings:
    get:
      operationId: getSettings
      summary: Return settings, currency configuration, rates, and authentication methods
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped settings workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SettingsRead"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
    put:
      operationId: updateSettings
      summary: Replace the current user's application settings
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SettingsMutationRequest"
      responses:
        "200":
          description: Settings updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MutationStatusResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /instruments:
    get:
      operationId: listInstruments
      summary: List the current user's investment instruments
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped instruments and latest prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [instruments]
                properties:
                  instruments:
                    type: array
                    items:
                      $ref: "#/components/schemas/Instrument"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createInstrument
      summary: Create an investment instrument
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstrumentMutationRequest"
      responses:
        "201":
          description: Instrument created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /instruments/{id}:
    get:
      operationId: getInstrument
      summary: Return one investment instrument and its price history
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200":
          description: Owner-scoped instrument detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstrumentDetail"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    put:
      operationId: updateInstrument
      summary: Replace an investment instrument
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstrumentMutationRequest"
      responses:
        "204": { description: Instrument updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deleteInstrument
      summary: Delete an unreferenced investment instrument
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Instrument deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /instruments/{id}/archive:
    patch:
      operationId: setInstrumentArchived
      summary: Archive or restore an investment instrument
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveMutationRequest"
      responses:
        "204": { description: Instrument archive state updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /security-prices:
    put:
      operationId: upsertSecurityPrice
      summary: Create or replace an instrument price for a date
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Price is an exact positive decimal string.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SecurityPriceMutationRequest"
      responses:
        "200":
          description: Security price upserted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /security-prices/{id}:
    delete:
      operationId: deleteSecurityPrice
      summary: Delete an instrument price
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Security price deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /position-events:
    post:
      operationId: createPositionEvent
      summary: Create ordinary investment position activity
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Quantities, prices, monetary values, and exchange rates are exact decimal strings; idempotency is supplied in the JSON body.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PositionEventCreateRequest"
      responses:
        "201":
          description: Position event created or an existing idempotent event returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /position-events/{id}:
    put:
      operationId: updatePositionEvent
      summary: Replace ordinary investment position activity
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The event cannot move between accounts.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PositionEventUpdateRequest"
      responses:
        "200":
          description: Position event updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deletePositionEvent
      summary: Delete ordinary investment position activity
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Position event deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /position-reconciliations:
    post:
      operationId: createPositionReconciliation
      summary: Record a reported position-account total
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Reported amounts are major-unit decimal strings in the account currency.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PositionReconciliationCreateRequest"
      responses:
        "201":
          description: Position reconciliation created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceIDResponse"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /position-reconciliations/{id}:
    delete:
      operationId: deletePositionReconciliation
      summary: Delete a position-account reconciliation
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Position reconciliation deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /account-conversions/preview:
    post:
      operationId: previewAccountConversion
      summary: Preview converting a balance account into a position account
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Monetary inputs are major-unit decimal strings; preview also requires a UUID idempotency key in the body or `Idempotency-Key` header.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountConversionRequest"
      responses:
        "200":
          description: Account conversion preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountConversionPreview"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /account-conversions:
    post:
      operationId: executeAccountConversion
      summary: Convert a balance account into a position account
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Supply a UUID in the body or `Idempotency-Key`; when both are present they must match.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountConversionRequest"
      responses:
        "200":
          description: An idempotent account conversion was replayed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountConversionResult"
        "201":
          description: Account converted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountConversionResult"
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /corporate-actions/stock-splits:
    post:
      operationId: recordStockSplit
      summary: Record an idempotent stock split
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Ratios are exact positive decimal strings. The account, instrument, and resulting event group are owner-scoped.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/StockSplitRequest" }
      responses:
        "201": { $ref: "#/components/responses/CorporateActionCreated" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /corporate-actions/spinoffs:
    post:
      operationId: recordSpinoff
      summary: Record an idempotent security spinoff
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Ratios are exact positive decimal strings. All referenced resources are owner-scoped.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SpinoffRequest" }
      responses:
        "201": { $ref: "#/components/responses/CorporateActionCreated" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /corporate-actions/mergers:
    post:
      operationId: recordMerger
      summary: Record an idempotent security merger
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Ratios are exact positive decimal strings. All referenced resources are owner-scoped.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MergerRequest" }
      responses:
        "201": { $ref: "#/components/responses/CorporateActionCreated" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /corporate-actions/dividend-reinvestments:
    post:
      operationId: recordDividendReinvestment
      summary: Record an idempotent dividend reinvestment
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Money inputs are major-unit decimal strings; quantities, prices, and exchange rates are exact decimal strings. All resources are owner-scoped.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/DividendReinvestmentRequest" }
      responses:
        "201": { $ref: "#/components/responses/CorporateActionCreated" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /corporate-actions/in-kind-transfers:
    post:
      operationId: recordInKindTransfer
      summary: Record an idempotent in-kind transfer
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Quantity and fee are major-unit decimal strings. Both accounts and the instrument must belong to the current user.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/InKindTransferRequest" }
      responses:
        "201": { $ref: "#/components/responses/CorporateActionCreated" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /corporate-actions/{id}:
    delete:
      operationId: deleteCorporateActionGroup
      summary: Delete a corporate-action event group
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Only an event group owned by the current user can be deleted.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Corporate-action event group deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/history-import/preview:
    post:
      operationId: previewAccountHistoryImport
      summary: Validate and preview a balance-account history import
      description: "Bearer API keys require `imports:write`. Browser sessions require a trusted Origin and `X-CSRF-Token`. The raw body or multipart file is limited to 5 MiB; multipart request overhead is limited to an additional 1 MiB. Results and balances are owner-scoped and returned with `Cache-Control: no-store`."
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        $ref: "#/components/requestBodies/ImportPreview"
      responses:
        "200":
          description: Import preview with a content hash for commit
          headers: { Cache-Control: { $ref: "#/components/headers/NoStore" } }
          content:
            application/json:
              schema:
                { $ref: "#/components/schemas/AccountHistoryImportResult" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "413": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/history-import/commit:
    post:
      operationId: commitAccountHistoryImport
      summary: Commit a previously previewed balance-account history import
      description: "Bearer API keys require `imports:write`. Browser sessions require a trusted Origin and `X-CSRF-Token`. Send the preview hash in `X-Preview-Hash` for raw JSON/CSV or in multipart field `hash`; it must match the exact content. The 5 MiB file and 1 MiB multipart-overhead limits apply. Results use `Cache-Control: no-store`."
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/PreviewHash"
      requestBody:
        $ref: "#/components/requestBodies/ImportCommit"
      responses:
        "200":
          description: Committed import result
          headers: { Cache-Control: { $ref: "#/components/headers/NoStore" } }
          content:
            application/json:
              schema:
                { $ref: "#/components/schemas/AccountHistoryImportResult" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "413": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/investment-import/preview:
    post:
      operationId: previewInvestmentHistoryImport
      summary: Validate and preview a position-account history import
      description: "Bearer API keys require `imports:write`. Browser sessions require a trusted Origin and `X-CSRF-Token`. The raw body or multipart file is limited to 5 MiB; multipart request overhead is limited to an additional 1 MiB. Results, positions, and values are owner-scoped and returned with `Cache-Control: no-store`."
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        $ref: "#/components/requestBodies/ImportPreview"
      responses:
        "200":
          description: Import preview with a content hash for commit
          headers: { Cache-Control: { $ref: "#/components/headers/NoStore" } }
          content:
            application/json:
              schema:
                { $ref: "#/components/schemas/InvestmentHistoryImportResult" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "413": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /accounts/{accountID}/investment-import/commit:
    post:
      operationId: commitInvestmentHistoryImport
      summary: Commit a previously previewed position-account history import
      description: "Bearer API keys require `imports:write`. Browser sessions require a trusted Origin and `X-CSRF-Token`. Send the preview hash in `X-Preview-Hash` for raw JSON/CSV or in multipart field `hash`; it must match the exact content. The 5 MiB file and 1 MiB multipart-overhead limits apply. Results use `Cache-Control: no-store`."
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MutationCSRFToken"
        - $ref: "#/components/parameters/PreviewHash"
      requestBody:
        $ref: "#/components/requestBodies/ImportCommit"
      responses:
        "200":
          description: Committed import result
          headers: { Cache-Control: { $ref: "#/components/headers/NoStore" } }
          content:
            application/json:
              schema:
                { $ref: "#/components/schemas/InvestmentHistoryImportResult" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "413": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /exports/user:
    get:
      operationId: exportUserArchive
      summary: Download the current user's portable JSON archive
      description: Bearer API keys require `exports:read`; authenticated browser sessions may also export. The download contains private owner-scoped financial and estate data, excludes authentication secrets and user IDs, and must not be cached.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      responses:
        "200":
          description: Versioned Wealthboard user archive
          headers:
            Content-Disposition:
              { $ref: "#/components/headers/UserArchiveDisposition" }
            Cache-Control: { $ref: "#/components/headers/NoStore" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UserArchive" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "413": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /exports/transactions.csv:
    get:
      operationId: exportTransactionsCsv
      summary: Download the current user's transactions as CSV
      description: Bearer API keys require `exports:read`; authenticated browser sessions may also export. The private owner-scoped export must not be cached. Monetary columns use integer minor units.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      responses:
        "200":
          description: UTF-8 transaction CSV
          headers:
            Content-Disposition:
              { $ref: "#/components/headers/TransactionsDisposition" }
            Cache-Control: { $ref: "#/components/headers/NoStore" }
          content:
            text/csv:
              schema: { type: string, contentMediaType: "text/csv" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /exports/accounts.csv:
    get:
      operationId: exportAccountsCsv
      summary: Download the current user's accounts as CSV
      description: Bearer API keys require `exports:read`; authenticated browser sessions may also export. The private owner-scoped export must not be cached. Monetary columns use integer minor units.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      responses:
        "200":
          description: UTF-8 account CSV
          headers:
            Content-Disposition:
              { $ref: "#/components/headers/AccountsDisposition" }
            Cache-Control: { $ref: "#/components/headers/NoStore" }
          content:
            text/csv:
              schema: { type: string, contentMediaType: "text/csv" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /restore/user:
    post:
      operationId: restoreUserArchive
      summary: Replace the current user's portable data from an archive
      description: Requires a browser session, trusted Origin, and `X-CSRF-Token`; Bearer API keys are not accepted. Accepts a raw JSON archive or one multipart `file`. Archive content is limited to 25 MiB; the raw HTTP body permits at most 1 MiB additional multipart overhead. Restore validates owner-scoped relationships and never restores authentication secrets or another user's identity.
      security: [{ sessionCookie: [] }]
      parameters:
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UserArchive" }
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: Versioned JSON archive, maximum 25 MiB.
      responses:
        "200":
          description: Counts of restored records
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RestoreSummary" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "413": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate:
    get:
      operationId: getEstateWorkspace
      summary: Return the current user's estate-planning workspace
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped estate workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EstateWorkspace"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /estate/plan:
    put:
      operationId: updateEstatePlan
      summary: Update the current user's estate plan
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Estate planning data is private and owner-scoped.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EstatePlanInput" }
      responses:
        "200":
          description: Updated estate plan
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EstatePlan" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/beneficiaries:
    post:
      operationId: createEstateBeneficiary
      summary: Create an estate beneficiary
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Contact summaries and notes are private, owner-scoped planning data.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BeneficiaryInput" }
      responses:
        "201":
          description: Beneficiary created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResourceIDResponse" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/beneficiaries/{id}:
    put:
      operationId: updateEstateBeneficiary
      summary: Replace an estate beneficiary
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The beneficiary must belong to the current user.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BeneficiaryInput" }
      responses:
        "204": { description: Beneficiary updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/beneficiaries/{id}/archive:
    patch:
      operationId: setEstateBeneficiaryArchived
      summary: Archive or restore an estate beneficiary
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The beneficiary must belong to the current user.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              { $ref: "#/components/schemas/RequiredArchiveMutationRequest" }
      responses:
        "204": { description: Beneficiary archive state updated }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/directives/{id}:
    put:
      operationId: upsertEstateDirective
      summary: Create or update an estate directive for an account
      description: The path `id` is an owner-scoped account ID. Requires `portfolio:write`; browser sessions also require a trusted Origin and `X-CSRF-Token`. Ownership is represented as integer basis points, where 10,000 is 100%.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EstateDirectiveInput" }
      responses:
        "200":
          description: Directive identifier
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResourceIDResponse" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/allocations/{id}:
    put:
      operationId: upsertEstateAllocation
      summary: Create or update an allocation for an estate directive
      description: The path `id` is an owner-scoped directive ID. Requires `portfolio:write`; browser sessions also require a trusted Origin and `X-CSRF-Token`. Allocation is integer basis points and each tier cannot exceed 10,000 total.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EstateAllocationInput" }
      responses:
        "200":
          description: Allocation identifier
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResourceIDResponse" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deleteEstateAllocation
      summary: Delete an estate allocation
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The allocation must belong to the current user.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Allocation deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/residuary:
    put:
      operationId: upsertEstateResiduaryAllocation
      summary: Create or update a residuary estate allocation
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. Beneficiaries are owner-scoped; allocation is integer basis points and each tier cannot exceed 10,000 total.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/EstateAllocationInput" }
      responses:
        "200":
          description: Residuary allocation identifier
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ResourceIDResponse" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/residuary/{id}:
    delete:
      operationId: deleteEstateResiduaryAllocation
      summary: Delete a residuary estate allocation
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The allocation must belong to the current user.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Residuary allocation deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/snapshots:
    post:
      operationId: createEstateSnapshot
      summary: Create an immutable estate-plan snapshot
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The private snapshot captures only the current user's plan and financial data and is not a legally executed will.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      responses:
        "201":
          description: Created immutable estate snapshot
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EstateSnapshot" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /estate/snapshots/{id}:
    get:
      operationId: getEstateSnapshot
      summary: Return one immutable estate snapshot
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`.
      security:
        - sessionCookie: []
        - apiKey: []
      parameters:
        - $ref: "#/components/parameters/ResourceID"
      responses:
        "200":
          description: Owner-scoped estate snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EstateSnapshot"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    delete:
      operationId: deleteEstateSnapshot
      summary: Delete an immutable estate snapshot
      description: Requires `portfolio:write`. Browser sessions also require a trusted Origin and `X-CSRF-Token`. The snapshot must belong to the current user.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters:
        - $ref: "#/components/parameters/ResourceID"
        - $ref: "#/components/parameters/MutationCSRFToken"
      responses:
        "204": { description: Estate snapshot deleted }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "404": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
  /ai:
    get:
      operationId: getAIReadModel
      summary: Return AI provider metadata, usage, and review availability
      description: Authenticate with a browser session or a Bearer API key that grants `portfolio:read`. Stored API key secrets are never returned.
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Owner-scoped AI configuration and usage metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AIRead"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
  /ai/settings:
    put:
      operationId: saveAISettings
      summary: Save the current user's AI provider settings
      description: Requires a browser session, trusted Origin, and `X-CSRF-Token`; Bearer API keys are not accepted. The JSON body is limited to 16 KiB. Stored API key ciphertext is never returned.
      security: [{ sessionCookie: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AISettingsInput" }
      responses:
        "200":
          description: Saved settings with redacted credential metadata
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AIWorkflowSettings" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: disconnectAIProvider
      summary: Delete AI settings and disconnect the provider
      description: "Requires a browser session, trusted Origin, and `X-CSRF-Token`; Bearer API keys are not accepted. Removes owner-scoped settings and stored credential material and returns `Cache-Control: no-store`."
      security: [{ sessionCookie: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      responses:
        "204":
          description: Provider disconnected
          headers: { Cache-Control: { $ref: "#/components/headers/NoStore" } }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
  /ai/credential:
    post:
      operationId: saveAICredential
      summary: Encrypt and store an AI provider API key
      description: Requires a browser session, trusted Origin, and `X-CSRF-Token`; Bearer API keys are not accepted. The JSON body is limited to 8 KiB. The plaintext key is used only for encryption and is never returned or logged.
      security: [{ sessionCookie: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AICredentialInput" }
      responses:
        "200":
          description: Settings with redacted credential metadata
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AIWorkflowSettings" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
    delete:
      operationId: deleteAICredential
      summary: Delete the stored AI provider credential
      description: "Requires a browser session, trusted Origin, and `X-CSRF-Token`; Bearer API keys are not accepted. Deletes only the current user's encrypted credential and returns `Cache-Control: no-store`."
      security: [{ sessionCookie: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      responses:
        "204":
          description: Stored credential deleted
          headers: { Cache-Control: { $ref: "#/components/headers/NoStore" } }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
  /ai/usage/clear:
    post:
      operationId: clearAIUsage
      summary: Delete the current user's AI usage history
      description: Requires a browser session, trusted Origin, and `X-CSRF-Token`; Bearer API keys are not accepted. Only owner-scoped usage events are deleted.
      security: [{ sessionCookie: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      responses:
        "200":
          description: Number of usage events deleted
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AIClearUsageResult" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
  /ai/review:
    post:
      operationId: createAIReview
      summary: Generate a review from a supplied portfolio snapshot
      description: Bearer API keys require `ai:invoke`. Browser sessions require a trusted Origin and `X-CSRF-Token`. The JSON body is limited to 40 KiB and the embedded snapshot to 25,000 bytes. Exact amounts and account names are sent only when the explicit sharing flags permit them. A request API key is ephemeral and never returned, stored, or logged.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIReviewRequest" }
      responses:
        "200":
          description: Grounded review, echoed snapshot, redacted provider metadata, and usage
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AIReviewResult" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
  /ai/import/convert:
    post:
      operationId: convertAIImportSource
      summary: Convert extracted source units into an import draft
      description: Bearer API keys require `ai:invoke`. Browser sessions require a trusted Origin and `X-CSRF-Token`. The JSON body is limited to 5 MiB plus 128 KiB, while the encoded source itself remains limited to 64 KiB and 1,000 units. Consent and a matching settings/destination hash are mandatory. Source text is treated as untrusted data. An ephemeral API key is never returned, stored, or logged.
      security: [{ sessionCookie: [] }, { apiKey: [] }]
      parameters: [{ $ref: "#/components/parameters/MutationCSRFToken" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/AIConversionRequest" }
      responses:
        "200":
          description: Import draft and complete source-reference accounting
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AIConversionDraft" }
        "400": { $ref: "#/components/responses/Problem" }
        "401": { $ref: "#/components/responses/Problem" }
        "403": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
        "429": { $ref: "#/components/responses/Problem" }
        "502": { $ref: "#/components/responses/Problem" }
        "503": { $ref: "#/components/responses/Problem" }
        "504": { $ref: "#/components/responses/Problem" }
  /api-keys:
    get:
      operationId: listApiKeys
      summary: List the current user's API keys
      security:
        - sessionCookie: []
      responses:
        "200":
          description: API key metadata without secrets or hashes
          content:
            application/json:
              schema:
                type: object
                required: [keys]
                properties:
                  keys:
                    type: array
                    items:
                      $ref: "#/components/schemas/APIKeyMetadata"
        "401":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createApiKey
      summary: Create an API key and return its secret once
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAPIKeyRequest"
      responses:
        "201":
          description: API key created; token is returned only in this response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/APIKeyMetadata"
                  - type: object
                    required: [token]
                    properties:
                      token:
                        type: string
                        writeOnly: true
        "401":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
  /api-keys/{id}:
    delete:
      operationId: revokeApiKey
      summary: Revoke one API key owned by the current user
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: API key revoked
        "404":
          $ref: "#/components/responses/Problem"
  /api-keys/revoke-all:
    post:
      operationId: revokeAllApiKeys
      summary: Revoke every active API key owned by the current user
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      responses:
        "200":
          description: API keys revoked
          content:
            application/json:
              schema:
                type: object
                required: [revoked]
                properties:
                  revoked:
                    type: integer
                    minimum: 0
        "401":
          $ref: "#/components/responses/Problem"
  /auth/signup:
    post:
      operationId: signup
      summary: Create a local user and browser session
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignupRequest"
      responses:
        "200":
          description: Account and session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "409":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/Problem"
  /auth/login:
    post:
      operationId: login
      summary: Create a local browser session
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/Problem"
  /auth/oidc/start:
    get:
      operationId: startOidcLogin
      summary: Start an OIDC Authorization Code with PKCE sign-in
      security: []
      parameters:
        - name: next
          in: query
          schema:
            type: string
            default: /
      responses:
        "303":
          description: Redirect to the configured OIDC provider
          headers:
            Location:
              schema:
                type: string
                format: uri
        "404":
          $ref: "#/components/responses/Problem"
  /auth/oidc/callback:
    get:
      operationId: completeOidcAuthentication
      summary: Complete an OIDC login, link, or reauthentication transaction
      security: []
      parameters:
        - name: state
          in: query
          required: true
          schema:
            type: string
        - name: code
          in: query
          schema:
            type: string
        - name: error
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Session established and browser handoff returned
          content:
            text/html:
              schema:
                type: string
        "303":
          description: Login failure redirected to the login page
        "404":
          $ref: "#/components/responses/Problem"
  /auth/oidc/link:
    post:
      operationId: startOidcLink
      summary: Start linking the configured OIDC provider after local password verification
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OidcLinkRequest"
      responses:
        "303":
          description: Redirect to the configured OIDC provider
        "401":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
    delete:
      operationId: unlinkOidcIdentity
      summary: Unlink OIDC after local password verification
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasswordConfirmationRequest"
      responses:
        "200":
          description: OIDC unlinked and replacement session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
  /auth/oidc/reauth:
    post:
      operationId: startOidcReauthentication
      summary: Start fresh OIDC authentication for local credential management
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
        - name: next
          in: query
          schema:
            type: string
            default: /settings
      responses:
        "303":
          description: Redirect to the configured OIDC provider
        "401":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
  /auth/local-credential:
    post:
      operationId: enableLocalCredential
      summary: Enable local sign-in after fresh OIDC reauthentication
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnableLocalCredentialRequest"
      responses:
        "200":
          description: Local credential enabled and replacement session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
    delete:
      operationId: removeLocalCredential
      summary: Remove local sign-in after fresh OIDC reauthentication
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      responses:
        "200":
          description: Local credential removed and replacement session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
  /auth/logout:
    post:
      operationId: logout
      summary: End the current browser session
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      responses:
        "200":
          description: Session ended
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    const: signed_out
        "401":
          $ref: "#/components/responses/Problem"
  /auth/change-password:
    post:
      operationId: changePassword
      summary: Change the current user's local password
      security:
        - sessionCookie: []
      parameters:
        - $ref: "#/components/parameters/CSRFToken"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePasswordRequest"
      responses:
        "200":
          description: Password changed and replacement session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
  /auth/principal:
    get:
      operationId: getPrincipal
      summary: Inspect the effective browser-session or API-key principal
      security:
        - sessionCookie: []
        - apiKey: []
      responses:
        "200":
          description: Effective authenticated principal
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [userId, username, authMethod, scopes]
                properties:
                  userId:
                    type: string
                    format: uuid
                  username:
                    type: string
                  authMethod:
                    type: string
                    enum: [session, api_key]
                  scopes:
                    type: array
                    items:
                      $ref: "#/components/schemas/APIKeyScope"
        "401":
          $ref: "#/components/responses/Problem"
  /session:
    get:
      operationId: getSession
      summary: Return the current browser session
      security:
        - sessionCookie: []
      responses:
        "200":
          description: Current session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          $ref: "#/components/responses/Problem"
components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: wealthboard_session
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: wbk_v1
      description: API-key scopes are enforced per operation as documented in each operation description.
  parameters:
    CSRFToken:
      name: X-CSRF-Token
      in: header
      required: true
      schema:
        type: string
        minLength: 1
    MutationCSRFToken:
      name: X-CSRF-Token
      in: header
      required: false
      description: Required when authenticating with `sessionCookie`; ignored for Bearer API keys.
      schema:
        type: string
        minLength: 1
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: UUID request key. When also supplied in the JSON body, both values must match.
      schema:
        type: string
        format: uuid
    PreviewHash:
      name: X-Preview-Hash
      in: header
      required: false
      description: Required for raw JSON or CSV commit bodies. Lowercase SHA-256 hash returned by preview. Multipart commits instead use the required `hash` form field.
      schema:
        type: string
        pattern: "^[a-f0-9]{64}$"
    AccountID:
      name: accountID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ResourceID:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ArchivedFilter:
      name: archived
      in: query
      description: Select active accounts, archived accounts, or both.
      schema:
        type: string
        enum: [active, archived, all]
        default: active
    AccountIDFilter:
      name: accountId
      in: query
      schema:
        type: string
        format: uuid
    TransactionType:
      name: type
      in: query
      schema:
        $ref: "#/components/schemas/TransactionType"
    FromDate:
      name: from
      in: query
      description: Inclusive start date.
      schema:
        type: string
        format: date
    ToDate:
      name: to
      in: query
      description: Inclusive end date; must not precede `from`.
      schema:
        type: string
        format: date
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
  headers:
    NoStore:
      description: Prevents storage of private financial or credential metadata.
      schema:
        type: string
        const: no-store
    UserArchiveDisposition:
      description: Attachment filename for the JSON user archive.
      schema:
        type: string
        const: 'attachment; filename="wealthboard-export.json"'
    TransactionsDisposition:
      description: Attachment filename for the transaction CSV.
      schema:
        type: string
        const: 'attachment; filename="wealthboard-transactions.csv"'
    AccountsDisposition:
      description: Attachment filename for the account CSV.
      schema:
        type: string
        const: 'attachment; filename="wealthboard-accounts.csv"'
  requestBodies:
    ImportPreview:
      required: true
      description: A raw JSON/CSV body up to 5 MiB, or multipart data containing one file up to 5 MiB and at most 1 MiB additional request overhead. Multipart `format` is needed only when the filename has no `.csv` or `.json` extension.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/AccountHistoryImportEnvelope"
              - $ref: "#/components/schemas/InvestmentHistoryImportEnvelope"
        text/csv:
          schema:
            { type: string, contentMediaType: "text/csv", maxLength: 5242880 }
        application/csv:
          schema:
            { type: string, contentMediaType: "text/csv", maxLength: 5242880 }
        multipart/form-data:
          schema:
            type: object
            additionalProperties: false
            required: [file]
            properties:
              file:
                type: string
                format: binary
                description: CSV or JSON file, maximum 5 MiB.
              format: { type: string, enum: [csv, json] }
    ImportCommit:
      required: true
      description: The exact previously previewed content. Raw JSON/CSV uses `X-Preview-Hash`; multipart uses its required `hash` field. File and overhead limits are identical to preview.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/AccountHistoryImportEnvelope"
              - $ref: "#/components/schemas/InvestmentHistoryImportEnvelope"
        text/csv:
          schema:
            { type: string, contentMediaType: "text/csv", maxLength: 5242880 }
        application/csv:
          schema:
            { type: string, contentMediaType: "text/csv", maxLength: 5242880 }
        multipart/form-data:
          schema:
            type: object
            additionalProperties: false
            required: [file, hash]
            properties:
              file:
                type: string
                format: binary
                description: CSV or JSON file, maximum 5 MiB.
              format: { type: string, enum: [csv, json] }
              hash: { type: string, pattern: "^[a-f0-9]{64}$" }
  schemas:
    AuthConfig:
      type: object
      additionalProperties: false
      required: [localEnabled, oidcEnabled, providerName]
      properties:
        localEnabled: { type: boolean }
        oidcEnabled: { type: boolean }
        providerName: { type: string }
    Overview:
      type: object
      additionalProperties: false
      required:
        [
          settings,
          totals,
          accounts,
          accountCount,
          goalCount,
          currentComplete,
          missingCurrencies,
        ]
      properties:
        settings:
          type: object
          required:
            [
              displayName,
              appName,
              baseCurrency,
              timezone,
              preferredDateFormat,
              defaultDashboardPeriod,
            ]
          properties:
            displayName: { type: string }
            appName: { type: string }
            baseCurrency: { type: string }
            timezone: { type: string }
            preferredDateFormat: { type: string }
            defaultDashboardPeriod: { type: string }
        totals:
          type: object
          required: [assets, liabilities, netWorth, liquid, investible]
          properties:
            assets: { type: string, pattern: "^-?[0-9]+$" }
            liabilities: { type: string, pattern: "^-?[0-9]+$" }
            netWorth: { type: string, pattern: "^-?[0-9]+$" }
            liquid: { type: string, pattern: "^-?[0-9]+$" }
            investible: { type: string, pattern: "^-?[0-9]+$" }
        accounts:
          type: array
          items:
            type: object
            required:
              [
                id,
                name,
                currency,
                currentValueMinor,
                isLiability,
                isIncludedInNetWorth,
                categoryName,
              ]
            properties:
              id: { type: string, format: uuid }
              name: { type: string }
              currency: { type: string }
              currentValueMinor: { type: string, pattern: "^-?[0-9]+$" }
              isLiability: { type: boolean }
              isIncludedInNetWorth: { type: boolean }
              categoryName: { type: string }
              institutionName: { type: string }
        accountCount: { type: integer, minimum: 0 }
        goalCount: { type: integer, minimum: 0 }
        currentComplete: { type: boolean }
        missingCurrencies:
          type: array
          items: { type: string }
    MinorUnits:
      type: string
      description: Integer monetary amount in the currency's minor units.
      pattern: "^-?[0-9]+$"
    DecimalString:
      type: string
      description: Exact decimal value serialized as a string.
      pattern: "^-?[0-9]+(?:\\.[0-9]+)?$"
    NonNegativeDecimalString:
      type: string
      description: Exact non-negative decimal value serialized as a string.
      pattern: "^[0-9]+(?:\\.[0-9]+)?$"
    PositiveDecimalString:
      type: string
      description: Exact positive decimal value serialized as a string.
      pattern: "^(?:0*[1-9][0-9]*)(?:\\.[0-9]+)?$|^0*\\.[0-9]*[1-9][0-9]*$"
    CurrencyCode:
      type: string
      pattern: "^[A-Z]{3}$"
    EventGroupResponse:
      type: object
      additionalProperties: false
      required: [eventGroupId]
      properties:
        eventGroupId: { type: string, format: uuid }
    StockSplitRequest:
      type: object
      additionalProperties: false
      required: [accountId, instrumentId, numerator, denominator, actionDate]
      properties:
        accountId: { type: string, format: uuid }
        instrumentId: { type: string, format: uuid }
        numerator: { $ref: "#/components/schemas/PositiveDecimalString" }
        denominator: { $ref: "#/components/schemas/PositiveDecimalString" }
        actionDate: { type: string, format: date }
        idempotencyKey:
          {
            type: string,
            format: uuid,
            description: Required unless supplied in `Idempotency-Key`.,
          }
        notes: { type: string, maxLength: 2000 }
    SpinoffRequest:
      type: object
      additionalProperties: false
      required:
        [
          accountId,
          sourceInstrumentId,
          newInstrumentId,
          numerator,
          denominator,
          actionDate,
        ]
      properties:
        accountId: { type: string, format: uuid }
        sourceInstrumentId: { type: string, format: uuid }
        newInstrumentId: { type: string, format: uuid }
        numerator: { $ref: "#/components/schemas/PositiveDecimalString" }
        denominator: { $ref: "#/components/schemas/PositiveDecimalString" }
        actionDate: { type: string, format: date }
        idempotencyKey:
          {
            type: string,
            format: uuid,
            description: Required unless supplied in `Idempotency-Key`.,
          }
        notes: { type: string, maxLength: 2000 }
    MergerRequest:
      type: object
      additionalProperties: false
      required:
        [
          accountId,
          sourceInstrumentId,
          destinationInstrumentId,
          numerator,
          denominator,
          actionDate,
        ]
      properties:
        accountId: { type: string, format: uuid }
        sourceInstrumentId: { type: string, format: uuid }
        destinationInstrumentId: { type: string, format: uuid }
        numerator: { $ref: "#/components/schemas/PositiveDecimalString" }
        denominator: { $ref: "#/components/schemas/PositiveDecimalString" }
        actionDate: { type: string, format: date }
        idempotencyKey:
          {
            type: string,
            format: uuid,
            description: Required unless supplied in `Idempotency-Key`.,
          }
        notes: { type: string, maxLength: 2000 }
    DividendReinvestmentRequest:
      type: object
      additionalProperties: false
      required:
        [
          accountId,
          instrumentId,
          dividendAmount,
          quantity,
          unitPrice,
          tradeCurrency,
          activityDate,
        ]
      properties:
        accountId: { type: string, format: uuid }
        instrumentId: { type: string, format: uuid }
        dividendAmount: { $ref: "#/components/schemas/PositiveDecimalString" }
        quantity: { $ref: "#/components/schemas/PositiveDecimalString" }
        unitPrice: { $ref: "#/components/schemas/PositiveDecimalString" }
        tradeCurrency: { $ref: "#/components/schemas/CurrencyCode" }
        feeAmount: { $ref: "#/components/schemas/NonNegativeDecimalString" }
        feeCurrency: { $ref: "#/components/schemas/CurrencyCode" }
        cashEffect: { $ref: "#/components/schemas/DecimalString" }
        appliedExchangeRate:
          { $ref: "#/components/schemas/PositiveDecimalString" }
        activityDate: { type: string, format: date }
        idempotencyKey:
          {
            type: string,
            format: uuid,
            description: Required unless supplied in `Idempotency-Key`.,
          }
        notes: { type: string, maxLength: 2000 }
    InKindTransferRequest:
      type: object
      additionalProperties: false
      required:
        [
          sourceAccountId,
          destinationAccountId,
          instrumentId,
          quantity,
          transferDate,
        ]
      properties:
        sourceAccountId: { type: string, format: uuid }
        destinationAccountId: { type: string, format: uuid }
        instrumentId: { type: string, format: uuid }
        quantity: { $ref: "#/components/schemas/PositiveDecimalString" }
        transferDate: { type: string, format: date }
        feeAmount: { $ref: "#/components/schemas/NonNegativeDecimalString" }
        idempotencyKey:
          {
            type: string,
            format: uuid,
            description: Required unless supplied in `Idempotency-Key`.,
          }
        notes: { type: string, maxLength: 2000 }
    AccountHistoryImportEnvelope:
      type: object
      additionalProperties: false
      required: [format, version, transactions]
      properties:
        format: { type: string }
        version: { type: integer }
        transactions:
          type: array
          items: { $ref: "#/components/schemas/AccountHistoryImportSourceRow" }
    AccountHistoryImportSourceRow:
      type: object
      additionalProperties: false
      required: [type, amount, date]
      properties:
        external_id: { type: [string, "null"] }
        type:
          type: string
          enum:
            [
              deposit,
              withdrawal,
              interest,
              dividend,
              capital_gain,
              capital_loss,
              fee,
              purchase,
              sale,
              manual_adjustment,
              liability_payment,
              liability_increase,
            ]
        amount: { $ref: "#/components/schemas/DecimalString" }
        date: { type: string, format: date }
        description: { type: [string, "null"] }
        notes: { type: [string, "null"] }
    InvestmentHistoryImportEnvelope:
      type: object
      additionalProperties: false
      required:
        [
          format,
          version,
          instruments,
          position_events,
          cash_transactions,
          prices,
        ]
      properties:
        format: { type: string }
        version: { type: integer }
        instruments:
          type: array
          items: { $ref: "#/components/schemas/InvestmentImportInstrument" }
        position_events:
          type: array
          items: { $ref: "#/components/schemas/InvestmentImportEvent" }
        cash_transactions:
          type: array
          items: { $ref: "#/components/schemas/InvestmentImportCash" }
        prices:
          type: array
          items: { $ref: "#/components/schemas/InvestmentImportPrice" }
    InvestmentImportInstrument:
      type: object
      additionalProperties: false
      required: [external_id, name, identifier_type, asset_type, quote_currency]
      properties:
        external_id: { type: string }
        name: { type: string }
        symbol: { type: [string, "null"] }
        identifier_type: { type: string }
        identifier: { type: [string, "null"] }
        exchange_mic: { type: [string, "null"] }
        asset_type: { type: string }
        quote_currency: { $ref: "#/components/schemas/CurrencyCode" }
    InvestmentImportEvent:
      type: object
      additionalProperties: false
      required:
        [
          external_id,
          instrument_external_id,
          type,
          quantity,
          trade_currency,
          trade_date,
        ]
      properties:
        external_id: { type: string }
        instrument_external_id: { type: string }
        type: { type: string }
        quantity: { $ref: "#/components/schemas/DecimalString" }
        unit_price:
          { type: [string, "null"], pattern: "^-?[0-9]+(?:\\.[0-9]+)?$" }
        trade_currency: { $ref: "#/components/schemas/CurrencyCode" }
        fee_amount:
          { type: [string, "null"], pattern: "^-?[0-9]+(?:\\.[0-9]+)?$" }
        fee_currency: { type: [string, "null"], pattern: "^[A-Z]{3}$" }
        cash_effect:
          { type: [string, "null"], pattern: "^-?[0-9]+(?:\\.[0-9]+)?$" }
        applied_exchange_rate:
          { type: [string, "null"], pattern: "^-?[0-9]+(?:\\.[0-9]+)?$" }
        opening_cost_basis:
          { type: [string, "null"], pattern: "^-?[0-9]+(?:\\.[0-9]+)?$" }
        event_group_id: { type: [string, "null"], format: uuid }
        trade_date: { type: string, format: date }
        settlement_date: { type: [string, "null"], format: date }
        description: { type: [string, "null"] }
        notes: { type: [string, "null"] }
    InvestmentImportCash:
      type: object
      additionalProperties: false
      required: [type, amount, date]
      properties:
        external_id: { type: [string, "null"] }
        type: { type: string }
        amount: { $ref: "#/components/schemas/DecimalString" }
        date: { type: string, format: date }
        event_group_id: { type: [string, "null"], format: uuid }
        description: { type: [string, "null"] }
        notes: { type: [string, "null"] }
    InvestmentImportPrice:
      type: object
      additionalProperties: false
      required:
        [external_id, instrument_external_id, price, effective_date, source]
      properties:
        external_id: { type: string }
        instrument_external_id: { type: string }
        price: { $ref: "#/components/schemas/PositiveDecimalString" }
        effective_date: { type: string, format: date }
        source: { type: string }
        provenance: { type: [string, "null"] }
    ImportAccount:
      type: object
      additionalProperties: false
      required: [id, name, currency]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        institution: { type: string }
        currency: { $ref: "#/components/schemas/CurrencyCode" }
    ImportDateRange:
      type: object
      additionalProperties: false
      required: [from, to]
      properties:
        from: { type: string, format: date }
        to: { type: string, format: date }
    AccountHistoryImportRow:
      type: object
      additionalProperties: false
      required: [row, externalId, status, code, message, transactionId]
      properties:
        row: { type: integer, minimum: 1 }
        externalId: { type: [string, "null"] }
        status: { type: string }
        code: { type: string }
        message: { type: string }
        transactionId: { type: [string, "null"], format: uuid }
        type: { type: string }
        amount:
          { type: string, description: Canonical major-unit decimal string. }
        date: { type: string, format: date }
    AccountHistoryImportSummary:
      type: object
      additionalProperties: false
      required: [skippedDuplicates, failed]
      properties:
        ready: { type: integer, minimum: 0 }
        imported: { type: integer, minimum: 0 }
        skippedDuplicates: { type: integer, minimum: 0 }
        failed: { type: integer, minimum: 0 }
    AccountHistoryImportResult:
      type: object
      additionalProperties: false
      required: [account, dateRange, summary, rows]
      properties:
        hash: { type: string, pattern: "^[a-f0-9]{64}$" }
        account: { $ref: "#/components/schemas/ImportAccount" }
        dateRange:
          oneOf:
            [{ $ref: "#/components/schemas/ImportDateRange" }, { type: "null" }]
        currentBalanceMinor:
          {
            type: integer,
            format: int64,
            description: Integer amount in account-currency minor units.,
          }
        projectedBalanceMinor:
          {
            type: integer,
            format: int64,
            description: Integer amount in account-currency minor units.,
          }
        finalBalanceMinor:
          {
            type: integer,
            format: int64,
            description: Integer amount in account-currency minor units.,
          }
        netChangeMinor:
          {
            type: integer,
            format: int64,
            description: Integer amount in account-currency minor units.,
          }
        summary: { $ref: "#/components/schemas/AccountHistoryImportSummary" }
        rows:
          type: array
          items: { $ref: "#/components/schemas/AccountHistoryImportRow" }
    InvestmentImportRow:
      type: object
      additionalProperties: false
      required: [collection, row, externalId, status, code, message]
      properties:
        collection: { type: string }
        row: { type: integer, minimum: 1 }
        externalId: { type: [string, "null"] }
        status: { type: string }
        code: { type: string }
        message: { type: string }
    InvestmentInstrumentChange:
      type: object
      additionalProperties: false
      required:
        [
          instrumentId,
          externalId,
          name,
          symbol,
          resolution,
          currentQuantity,
          projectedQuantity,
          quantityChange,
        ]
      properties:
        instrumentId: { type: string, format: uuid }
        externalId: { type: string }
        name: { type: string }
        symbol: { type: [string, "null"] }
        resolution: { type: string }
        currentQuantity: { $ref: "#/components/schemas/DecimalString" }
        projectedQuantity: { $ref: "#/components/schemas/DecimalString" }
        quantityChange: { $ref: "#/components/schemas/DecimalString" }
    InvestmentEventChange:
      type: object
      additionalProperties: false
      required:
        [
          externalId,
          instrumentId,
          type,
          tradeDate,
          eventSequence,
          beforeQuantity,
          afterQuantity,
        ]
      properties:
        externalId: { type: string }
        instrumentId: { type: string, format: uuid }
        type: { type: string }
        tradeDate: { type: string, format: date }
        eventSequence: { type: integer }
        beforeQuantity: { $ref: "#/components/schemas/DecimalString" }
        afterQuantity: { $ref: "#/components/schemas/DecimalString" }
    InvestmentPriceChange:
      type: object
      additionalProperties: false
      required:
        [externalId, instrumentId, price, currency, source, affectedFrom]
      properties:
        externalId: { type: string }
        instrumentId: { type: string, format: uuid }
        price: { $ref: "#/components/schemas/DecimalString" }
        currency: { $ref: "#/components/schemas/CurrencyCode" }
        source: { type: string }
        affectedFrom: { type: string, format: date }
    InvestmentImportValue:
      type: object
      additionalProperties: false
      required:
        [
          cashMinor,
          positionsMinor,
          totalMinor,
          complete,
          missingPrices,
          missingCurrencies,
        ]
      properties:
        cashMinor:
          {
            type: integer,
            format: int64,
            description: Integer account-currency minor units.,
          }
        positionsMinor:
          {
            type: integer,
            format: int64,
            description: Integer account-currency minor units.,
          }
        totalMinor:
          {
            type: integer,
            format: int64,
            description: Integer account-currency minor units.,
          }
        complete: { type: boolean }
        missingPrices: { type: array, items: { type: string } }
        missingCurrencies:
          { type: array, items: { $ref: "#/components/schemas/CurrencyCode" } }
    InvestmentImportSummary:
      type: object
      additionalProperties: false
      required: [records, skippedDuplicates, failed]
      properties:
        records: { type: integer, minimum: 0 }
        ready: { type: integer, minimum: 0 }
        imported: { type: integer, minimum: 0 }
        skippedDuplicates: { type: integer, minimum: 0 }
        failed: { type: integer, minimum: 0 }
    InvestmentHistoryImportResult:
      type: object
      additionalProperties: false
      required:
        [
          account,
          current,
          projected,
          netChangeMinor,
          dateRange,
          instrumentChanges,
          eventChanges,
          priceChanges,
          summary,
          canCommit,
          rows,
        ]
      properties:
        hash: { type: string, pattern: "^[a-f0-9]{64}$" }
        account: { $ref: "#/components/schemas/ImportAccount" }
        current: { $ref: "#/components/schemas/InvestmentImportValue" }
        projected: { $ref: "#/components/schemas/InvestmentImportValue" }
        finalBalanceMinor:
          {
            type: integer,
            format: int64,
            description: Integer account-currency minor units.,
          }
        netChangeMinor:
          {
            type: integer,
            format: int64,
            description: Integer account-currency minor units.,
          }
        dateRange:
          oneOf:
            [{ $ref: "#/components/schemas/ImportDateRange" }, { type: "null" }]
        instrumentChanges:
          {
            type: array,
            items: { $ref: "#/components/schemas/InvestmentInstrumentChange" },
          }
        eventChanges:
          {
            type: array,
            items: { $ref: "#/components/schemas/InvestmentEventChange" },
          }
        priceChanges:
          {
            type: array,
            items: { $ref: "#/components/schemas/InvestmentPriceChange" },
          }
        summary: { $ref: "#/components/schemas/InvestmentImportSummary" }
        canCommit: { type: boolean }
        rows:
          {
            type: array,
            items: { $ref: "#/components/schemas/InvestmentImportRow" },
          }
    PortableRecord:
      type: object
      description: One owner-scoped archive row. Database `*_minor` fields are integer minor units; rates, prices, quantities, and ratios are exact decimal strings. User ownership columns and authentication secrets are excluded.
      additionalProperties: true
    UserArchive:
      type: object
      additionalProperties: false
      required:
        [
          format,
          version,
          exportedAt,
          settings,
          categories,
          institutions,
          accounts,
          transactions,
          valuations,
          exchangeRates,
          goals,
          goalContributionPlans,
          goalMilestones,
          goalAlertDismissals,
          beneficiaries,
          estatePlans,
          estateAccountDirectives,
          estateAllocations,
          estateResiduaryAllocations,
          estatePlanSnapshots,
          investmentInstruments,
          positionEvents,
          securityPrices,
          positionReconciliations,
          accountConversions,
        ]
      properties:
        format: { type: string, const: wealthboard-user-export }
        version: { type: integer, const: 8 }
        exportedAt: { type: string, format: date-time }
        settings:
          {
            type: object,
            additionalProperties: true,
            description: Owner settings without credentials or session data.,
          }
        categories:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        institutions:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        accounts:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        transactions:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        valuations:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        exchangeRates:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        goals:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        goalContributionPlans:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        goalMilestones:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        goalAlertDismissals:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        beneficiaries:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        estatePlans:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        estateAccountDirectives:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        estateAllocations:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        estateResiduaryAllocations:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        estatePlanSnapshots:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        investmentInstruments:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        positionEvents:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        securityPrices:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        positionReconciliations:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
        accountConversions:
          {
            type: array,
            items: { $ref: "#/components/schemas/PortableRecord" },
          }
    RestoreSummary:
      type: object
      additionalProperties: false
      required:
        [
          institutions,
          accounts,
          transactions,
          goals,
          milestones,
          beneficiaries,
          estatePlans,
          estateSnapshots,
          investmentInstruments,
          positionEvents,
          securityPrices,
          positionReconciliations,
        ]
      properties:
        institutions: { type: integer, minimum: 0 }
        accounts: { type: integer, minimum: 0 }
        transactions: { type: integer, minimum: 0 }
        goals: { type: integer, minimum: 0 }
        milestones: { type: integer, minimum: 0 }
        beneficiaries: { type: integer, minimum: 0 }
        estatePlans: { type: integer, minimum: 0 }
        estateSnapshots: { type: integer, minimum: 0 }
        investmentInstruments: { type: integer, minimum: 0 }
        positionEvents: { type: integer, minimum: 0 }
        securityPrices: { type: integer, minimum: 0 }
        positionReconciliations: { type: integer, minimum: 0 }
    ResourceIDResponse:
      type: object
      additionalProperties: false
      required: [id]
      properties:
        id: { type: string, format: uuid }
    MutationStatusResponse:
      type: object
      additionalProperties: false
      required: [status]
      properties:
        status: { type: string }
    SettingsMutationRequest:
      type: object
      additionalProperties: false
      required:
        [
          displayName,
          appName,
          baseCurrency,
          timezone,
          preferredDateFormat,
          defaultDashboardPeriod,
          sessionTimeoutMinutes,
          positionStaleDaysStock,
          positionStaleDaysEtf,
          positionStaleDaysFund,
        ]
      properties:
        displayName: { type: string, minLength: 1, maxLength: 80 }
        appName: { type: string, minLength: 1, maxLength: 80 }
        baseCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        supportedCurrencies:
          type: array
          uniqueItems: true
          items:
            $ref: "#/components/schemas/CurrencyCode"
        timezone: { type: string, minLength: 1 }
        preferredDateFormat:
          type: string
          enum: [dd MMM yyyy, dd/MM/yyyy, MM/dd/yyyy, yyyy-MM-dd]
        defaultDashboardPeriod:
          type: string
          enum: [1m, 3m, 6m, 1y, all]
        sessionTimeoutMinutes: { type: integer, minimum: 15, maximum: 525600 }
        defaultGoalReturnBps: { type: integer, minimum: 0, maximum: 10000 }
        positionStaleDaysStock: { type: integer, minimum: 1 }
        positionStaleDaysEtf: { type: integer, minimum: 1 }
        positionStaleDaysFund: { type: integer, minimum: 1 }
    CategoryMutationRequest:
      type: object
      additionalProperties: false
      required: [name, icon, assetOrLiability]
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        icon: { type: string, minLength: 1, maxLength: 100 }
        assetOrLiability: { type: string, enum: [asset, liability] }
        description: { type: string, maxLength: 2000 }
        isLiquid: { type: boolean }
        isInvestible: { type: boolean }
    InstitutionMutationRequest:
      type: object
      additionalProperties: false
      required: [name, type]
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        type:
          type: string
          enum:
            [
              bank,
              credit_union,
              brokerage,
              asset_manager,
              pension_provider,
              insurer,
              lender,
              digital_wallet,
              government,
              employer,
              other,
            ]
        websiteUrl: { type: string, format: uri, maxLength: 500 }
        countryCode: { type: string, pattern: "^[A-Z]{2}$" }
        address: { type: string, maxLength: 500 }
        notes: { type: string, maxLength: 2000 }
    ExchangeRateMutationRequest:
      type: object
      additionalProperties: false
      required: [baseCurrency, quoteCurrency, rate, effectiveDate]
      properties:
        baseCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        quoteCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        rate:
          $ref: "#/components/schemas/PositiveDecimalString"
        effectiveDate: { type: string, format: date }
    ArchiveMutationRequest:
      type: object
      additionalProperties: false
      properties:
        archived: { type: boolean }
    RequiredArchiveMutationRequest:
      type: object
      additionalProperties: false
      required: [archived]
      properties:
        archived: { type: boolean }
    CategoryReorderRequest:
      type: object
      additionalProperties: false
      required: [direction]
      properties:
        direction: { type: string, enum: [up, down] }
    AccountCreateRequest:
      type: object
      additionalProperties: false
      required: [idempotencyKey, name, categoryId, currency, openingValueMinor]
      properties:
        idempotencyKey: { type: string, format: uuid }
        name: { type: string, minLength: 1, maxLength: 100 }
        description: { type: string, maxLength: 2000 }
        categoryId: { type: string, format: uuid }
        institutionId: { type: [string, "null"], format: uuid }
        accountReference: { type: string, maxLength: 50 }
        currency:
          $ref: "#/components/schemas/CurrencyCode"
        trackingMode:
          { type: string, enum: [balance, positions], default: balance }
        openingValueMinor:
          allOf:
            - $ref: "#/components/schemas/MinorUnits"
            - pattern: "^[0-9]+$"
        costBasisMinor:
          oneOf:
            - $ref: "#/components/schemas/MinorUnits"
            - type: "null"
        isIncludedInNetWorth: { type: boolean }
        notes: { type: string, maxLength: 2000 }
        openedAt: { type: [string, "null"], format: date }
    AccountUpdateRequest:
      type: object
      additionalProperties: false
      required: [name, categoryId, currency]
      properties:
        idempotencyKey: { type: string, format: uuid }
        name: { type: string, minLength: 1, maxLength: 100 }
        description: { type: string, maxLength: 2000 }
        categoryId: { type: string, format: uuid }
        institutionId: { type: [string, "null"], format: uuid }
        accountReference: { type: string, maxLength: 50 }
        currency:
          $ref: "#/components/schemas/CurrencyCode"
        trackingMode: { type: string, enum: [balance, positions] }
        openingValueMinor:
          $ref: "#/components/schemas/MinorUnits"
        costBasisMinor:
          oneOf:
            - $ref: "#/components/schemas/MinorUnits"
            - type: "null"
        isIncludedInNetWorth: { type: boolean }
        notes: { type: string, maxLength: 2000 }
        openedAt: { type: [string, "null"], format: date }
    AccountDeleteRequest:
      type: object
      additionalProperties: false
      required: [confirmationName]
      properties:
        confirmationName: { type: string }
    TransactionCreateRequest:
      type: object
      additionalProperties: false
      required: [idempotencyKey, accountId, type, amountMinor, transactionDate]
      properties:
        idempotencyKey: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        type:
          $ref: "#/components/schemas/MutableTransactionType"
        amountMinor:
          $ref: "#/components/schemas/MinorUnits"
        transactionDate: { type: string, format: date }
        description: { type: string, maxLength: 200 }
        externalId: { type: string, maxLength: 200 }
        notes: { type: string, maxLength: 2000 }
    TransactionUpdateRequest:
      type: object
      additionalProperties: false
      required: [type, amountMinor, transactionDate]
      properties:
        idempotencyKey: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        type:
          $ref: "#/components/schemas/MutableTransactionType"
        amountMinor:
          $ref: "#/components/schemas/MinorUnits"
        transactionDate: { type: string, format: date }
        description: { type: string, maxLength: 200 }
        externalId: { type: string, maxLength: 200 }
        notes: { type: string, maxLength: 2000 }
    MutableTransactionType:
      type: string
      enum:
        [
          deposit,
          withdrawal,
          interest,
          dividend,
          capital_gain,
          capital_loss,
          fee,
          purchase,
          sale,
          manual_adjustment,
          liability_payment,
          liability_increase,
        ]
    ValuationCreateRequest:
      type: object
      additionalProperties: false
      required: [idempotencyKey, accountId, valueMinor, valuationDate]
      properties:
        idempotencyKey: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        valueMinor:
          allOf:
            - $ref: "#/components/schemas/MinorUnits"
            - pattern: "^[0-9]+$"
        valuationDate: { type: string, format: date }
        notes: { type: string, maxLength: 2000 }
    TransferCreateRequest:
      type: object
      additionalProperties: false
      required:
        [
          idempotencyKey,
          fromAccountId,
          toAccountId,
          sourceAmountMinor,
          transactionDate,
        ]
      properties:
        idempotencyKey: { type: string, format: uuid }
        fromAccountId: { type: string, format: uuid }
        toAccountId: { type: string, format: uuid }
        sourceAmountMinor:
          allOf:
            - $ref: "#/components/schemas/MinorUnits"
            - pattern: "^[1-9][0-9]*$"
        destinationAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        transactionDate: { type: string, format: date }
        description: { type: string, maxLength: 200 }
    GoalMutationRequest:
      type: object
      additionalProperties: false
      required:
        [
          name,
          targetAmount,
          currency,
          targetDate,
          assumedAnnualReturn,
          plannedContribution,
          planStartDate,
        ]
      properties:
        idempotencyKey: { type: [string, "null"], format: uuid }
        name: { type: string, minLength: 1, maxLength: 100 }
        description: { type: [string, "null"], maxLength: 500 }
        targetAmount:
          $ref: "#/components/schemas/PositiveDecimalString"
        currentAmount:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        currency:
          $ref: "#/components/schemas/CurrencyCode"
        targetDate: { type: string, format: date }
        linkedAccountId: { type: [string, "null"], format: uuid }
        icon: { type: string, maxLength: 50, default: Target }
        status:
          {
            type: string,
            enum: [active, paused, completed, cancelled],
            default: active,
          }
        priority: { type: integer, minimum: 0, maximum: 100 }
        assumedAnnualReturn: { type: number, minimum: 0, maximum: 100 }
        plannedContribution:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        frequency:
          {
            type: string,
            enum: [weekly, monthly, quarterly, annually, custom],
            default: monthly,
          }
        planStartDate: { type: string, format: date }
        planEndDate: { type: string, format: date }
    GoalMutationResult:
      type: object
      additionalProperties: false
      required: [id, replayed]
      properties:
        id: { type: string, format: uuid }
        replayed: { type: boolean }
    GoalStatusRequest:
      type: object
      additionalProperties: false
      required: [status]
      properties:
        status: { type: string, enum: [active, paused, completed, cancelled] }
    GoalMilestoneCreateRequest:
      type: object
      additionalProperties: false
      required: [name, targetAmount]
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        targetAmount:
          $ref: "#/components/schemas/PositiveDecimalString"
        targetDate: { type: string, format: date }
    InstrumentMutationRequest:
      type: object
      additionalProperties: false
      required: [name, identifierType, assetType, quoteCurrency]
      properties:
        externalId: { type: string, maxLength: 200 }
        name: { type: string, minLength: 1, maxLength: 100 }
        symbol: { type: string, maxLength: 30 }
        identifierType: { type: string, enum: [isin, ticker_exchange, custom] }
        identifier: { type: string, maxLength: 100 }
        exchangeMic: { type: string, maxLength: 20 }
        assetType: { type: string, enum: [stock, etf, fund] }
        quoteCurrency:
          $ref: "#/components/schemas/CurrencyCode"
    SecurityPriceMutationRequest:
      type: object
      additionalProperties: false
      required: [instrumentId, price, effectiveDate]
      properties:
        instrumentId: { type: string, format: uuid }
        externalId: { type: string, maxLength: 200 }
        price:
          $ref: "#/components/schemas/PositiveDecimalString"
        effectiveDate: { type: string, format: date }
        source: { type: string, maxLength: 100, default: manual }
        provenance: { type: string, maxLength: 500 }
    PositionEventCreateRequest:
      type: object
      additionalProperties: false
      required:
        [accountId, instrumentId, type, quantity, tradeDate, idempotencyKey]
      properties:
        accountId: { type: string, format: uuid }
        instrumentId: { type: string, format: uuid }
        type:
          {
            type: string,
            enum: [opening_position, buy, sell, quantity_adjustment],
          }
        quantity:
          $ref: "#/components/schemas/DecimalString"
        unitPrice:
          $ref: "#/components/schemas/PositiveDecimalString"
        tradeCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        feeAmount:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        feeCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        cashEffect:
          $ref: "#/components/schemas/PositiveDecimalString"
        appliedExchangeRate:
          $ref: "#/components/schemas/PositiveDecimalString"
        openingCostBasis:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        tradeDate: { type: string, format: date }
        settlementDate: { type: string, format: date }
        externalId: { type: string, maxLength: 200 }
        idempotencyKey: { type: string, format: uuid }
        description: { type: string, maxLength: 200 }
        notes: { type: string, maxLength: 2000 }
    PositionEventUpdateRequest:
      type: object
      additionalProperties: false
      required: [accountId, instrumentId, type, quantity, tradeDate]
      properties:
        accountId: { type: string, format: uuid }
        instrumentId: { type: string, format: uuid }
        type:
          {
            type: string,
            enum: [opening_position, buy, sell, quantity_adjustment],
          }
        quantity:
          $ref: "#/components/schemas/DecimalString"
        unitPrice:
          $ref: "#/components/schemas/PositiveDecimalString"
        tradeCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        feeAmount:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        feeCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        cashEffect:
          $ref: "#/components/schemas/PositiveDecimalString"
        appliedExchangeRate:
          $ref: "#/components/schemas/PositiveDecimalString"
        openingCostBasis:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        tradeDate: { type: string, format: date }
        settlementDate: { type: string, format: date }
        externalId: { type: string, maxLength: 200 }
        idempotencyKey: { type: string, format: uuid }
        description: { type: string, maxLength: 200 }
        notes: { type: string, maxLength: 2000 }
    PositionReconciliationCreateRequest:
      type: object
      additionalProperties: false
      required: [accountId, observationDate, reportedTotal]
      properties:
        accountId: { type: string, format: uuid }
        observationDate: { type: string, format: date }
        reportedCash:
          $ref: "#/components/schemas/DecimalString"
        reportedTotal:
          $ref: "#/components/schemas/DecimalString"
        notes: { type: string, maxLength: 2000 }
    AccountConversionHoldingRequest:
      type: object
      additionalProperties: false
      required: [instrumentId, quantity, price]
      properties:
        instrumentId: { type: string, format: uuid }
        quantity:
          $ref: "#/components/schemas/PositiveDecimalString"
        price:
          $ref: "#/components/schemas/PositiveDecimalString"
        openingCostBasis:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        priceSource: { type: string, maxLength: 100, default: conversion }
        priceProvenance: { type: string, maxLength: 500 }
    AccountConversionRequest:
      type: object
      additionalProperties: false
      required:
        [sourceAccountId, targetName, conversionDate, openingCash, holdings]
      properties:
        sourceAccountId: { type: string, format: uuid }
        targetName: { type: string, minLength: 1, maxLength: 100 }
        conversionDate: { type: string, format: date }
        openingCash:
          $ref: "#/components/schemas/NonNegativeDecimalString"
        holdings:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: "#/components/schemas/AccountConversionHoldingRequest"
        idempotencyKey: { type: [string, "null"], format: uuid }
        confirmDifference: { type: boolean }
    AccountConversionHoldingPreview:
      type: object
      additionalProperties: false
      required: [instrumentId, name, symbol, quantity, price, quoteCurrency]
      properties:
        instrumentId: { type: string, format: uuid }
        name: { type: string }
        symbol: { type: [string, "null"] }
        quantity:
          $ref: "#/components/schemas/DecimalString"
        price:
          $ref: "#/components/schemas/DecimalString"
        quoteCurrency:
          $ref: "#/components/schemas/CurrencyCode"
    AccountConversionPreview:
      type: object
      additionalProperties: false
      required:
        [
          sourceAccountId,
          sourceAccountName,
          currency,
          conversionDate,
          sourceBalanceMinor,
          openingCashMinor,
          positionsMinor,
          projectedTotalMinor,
          differenceMinor,
          holdings,
        ]
      properties:
        sourceAccountId: { type: string, format: uuid }
        sourceAccountName: { type: string }
        currency:
          $ref: "#/components/schemas/CurrencyCode"
        conversionDate: { type: string, format: date }
        sourceBalanceMinor:
          $ref: "#/components/schemas/MinorUnits"
        openingCashMinor:
          $ref: "#/components/schemas/MinorUnits"
        positionsMinor:
          $ref: "#/components/schemas/MinorUnits"
        projectedTotalMinor:
          $ref: "#/components/schemas/MinorUnits"
        differenceMinor:
          $ref: "#/components/schemas/MinorUnits"
        holdings:
          type: array
          items:
            $ref: "#/components/schemas/AccountConversionHoldingPreview"
    AccountConversionResult:
      type: object
      additionalProperties: false
      required: [targetAccountId, replayed]
      properties:
        targetAccountId: { type: string, format: uuid }
        replayed: { type: boolean }
    TransactionType:
      type: string
      enum:
        - opening_balance
        - deposit
        - withdrawal
        - interest
        - dividend
        - capital_gain
        - capital_loss
        - fee
        - purchase
        - sale
        - manual_adjustment
        - liability_payment
        - liability_increase
        - transfer
    Category:
      type: object
      additionalProperties: false
      required:
        [
          id,
          name,
          slug,
          icon,
          displayOrder,
          assetOrLiability,
          isLiquid,
          isInvestible,
          isArchived,
          isSystem,
        ]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        slug: { type: string }
        icon: { type: string }
        displayOrder: { type: integer }
        assetOrLiability: { type: string }
        description: { type: string }
        isLiquid: { type: boolean }
        isInvestible: { type: boolean }
        isArchived: { type: boolean }
        isSystem: { type: boolean }
    Institution:
      type: object
      additionalProperties: false
      required: [id, name, type]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        type: { type: string }
        websiteUrl: { type: string }
        countryCode: { type: string }
        address: { type: string }
        notes: { type: string }
        archivedAt: { type: string, format: date-time }
    Account:
      type: object
      additionalProperties: false
      required:
        [
          id,
          categoryId,
          name,
          currency,
          trackingMode,
          currentValueMinor,
          convertedValueMinor,
          monthlyChangeMinor,
          isLiability,
          isIncludedInNetWorth,
          categoryName,
        ]
      properties:
        id: { type: string, format: uuid }
        categoryId: { type: string, format: uuid }
        institutionId: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        currency: { type: string }
        trackingMode: { type: string }
        currentValueMinor:
          $ref: "#/components/schemas/MinorUnits"
        convertedValueMinor:
          anyOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
        monthlyChangeMinor:
          anyOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
        costBasisMinor:
          $ref: "#/components/schemas/MinorUnits"
        isLiability: { type: boolean }
        isIncludedInNetWorth: { type: boolean }
        categoryName: { type: string }
        institutionName: { type: string }
        accountReference: { type: string }
        notes: { type: string }
        openedAt: { type: string, format: date }
        archivedAt: { type: string, format: date-time }
    Transaction:
      type: object
      additionalProperties: false
      required:
        [
          id,
          accountId,
          accountName,
          type,
          amountMinor,
          currency,
          transactionDate,
        ]
      properties:
        id: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        accountName: { type: string }
        type:
          $ref: "#/components/schemas/TransactionType"
        amountMinor:
          $ref: "#/components/schemas/MinorUnits"
        currency: { type: string }
        transactionDate: { type: string, format: date }
        description: { type: string }
        notes: { type: string }
        externalId: { type: string }
        transferGroupId: { type: string, format: uuid }
        eventGroupId: { type: string, format: uuid }
    Valuation:
      type: object
      additionalProperties: false
      required:
        [id, accountId, accountName, valueMinor, currency, valuationDate]
      properties:
        id: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        accountName: { type: string }
        valueMinor:
          $ref: "#/components/schemas/MinorUnits"
        currency: { type: string }
        valuationDate: { type: string, format: date }
        notes: { type: string }
    ActivityItem:
      type: object
      additionalProperties: false
      required:
        [kind, id, accountId, accountName, type, amountMinor, currency, date]
      properties:
        kind: { type: string, enum: [transaction, valuation, position, price] }
        id: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        accountName: { type: string }
        type: { type: string }
        amountMinor:
          $ref: "#/components/schemas/MinorUnits"
        currency: { type: string }
        date: { type: string, format: date }
        description: { type: string }
        notes: { type: string }
        instrumentId: { type: string, format: uuid }
        instrumentName: { type: string }
        instrumentSymbol: { type: string }
        quantity: { $ref: "#/components/schemas/DecimalString" }
        unitPrice: { $ref: "#/components/schemas/DecimalString" }
        eventGroupId: { type: string, format: uuid }
    TransactionPage:
      type: object
      additionalProperties: false
      required: [items, limit, offset, hasMore]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Transaction"
        limit: { type: integer, minimum: 1, maximum: 100 }
        offset: { type: integer, minimum: 0, maximum: 10000 }
        hasMore: { type: boolean }
    ValuationPage:
      type: object
      additionalProperties: false
      required: [items, limit, offset, hasMore]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Valuation"
        limit: { type: integer, minimum: 1, maximum: 100 }
        offset: { type: integer, minimum: 0, maximum: 10000 }
        hasMore: { type: boolean }
    ActivityPage:
      type: object
      additionalProperties: false
      required: [items, limit, offset, hasMore]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ActivityItem"
        limit: { type: integer, minimum: 1, maximum: 100 }
        offset: { type: integer, minimum: 0, maximum: 10000 }
        hasMore: { type: boolean }
    PositionEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - accountId
        - instrumentId
        - type
        - quantity
        - tradeCurrency
        - cashEffectMinor
        - tradeDate
        - eventSequence
        - createdAt
        - updatedAt
      properties:
        id: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        instrumentId: { type: string, format: uuid }
        relatedInstrumentId: { type: string, format: uuid }
        type:
          {
            type: string,
            enum:
              [
                opening_position,
                buy,
                sell,
                quantity_adjustment,
                transfer_in,
                transfer_out,
                split,
                spinoff,
                merger_in,
                merger_out,
              ],
          }
        quantity:
          $ref: "#/components/schemas/DecimalString"
        unitPrice:
          $ref: "#/components/schemas/PositiveDecimalString"
        tradeCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        feeAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        feeCurrency:
          $ref: "#/components/schemas/CurrencyCode"
        cashEffectMinor:
          $ref: "#/components/schemas/MinorUnits"
        appliedExchangeRate:
          $ref: "#/components/schemas/PositiveDecimalString"
        openingCostBasisMinor:
          $ref: "#/components/schemas/MinorUnits"
        actionRatioNumerator:
          $ref: "#/components/schemas/PositiveDecimalString"
        actionRatioDenominator:
          $ref: "#/components/schemas/PositiveDecimalString"
        tradeDate: { type: string, format: date }
        eventSequence: { type: integer, minimum: 0 }
        settlementDate: { type: string, format: date }
        externalId: { type: string }
        eventGroupId: { type: string, format: uuid }
        description: { type: string }
        notes: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    PositionEventPage:
      type: object
      additionalProperties: false
      required: [items, limit, offset, hasMore]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/PositionEvent"
        limit: { type: integer, minimum: 1, maximum: 100 }
        offset: { type: integer, minimum: 0, maximum: 10000 }
        hasMore: { type: boolean }
    PositionReconciliation:
      type: object
      additionalProperties: false
      required:
        [
          id,
          accountId,
          observationDate,
          reportedTotalMinor,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        observationDate: { type: string, format: date }
        reportedCashMinor:
          $ref: "#/components/schemas/MinorUnits"
        reportedTotalMinor:
          $ref: "#/components/schemas/MinorUnits"
        notes: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    PositionReconciliationPage:
      type: object
      additionalProperties: false
      required: [items, limit, offset, hasMore]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/PositionReconciliation"
        limit: { type: integer, minimum: 1, maximum: 100 }
        offset: { type: integer, minimum: 0, maximum: 10000 }
        hasMore: { type: boolean }
    GoalLinkedAccount:
      type: object
      additionalProperties: false
      required: [id, name, currency]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        currency: { type: string }
    GoalPlan:
      type: object
      additionalProperties: false
      required: [plannedContributionMinor, frequency, startDate, endDate]
      properties:
        plannedContributionMinor:
          $ref: "#/components/schemas/MinorUnits"
        frequency: { type: string }
        startDate: { type: string, format: date }
        endDate: { type: [string, "null"], format: date }
    Goal:
      type: object
      additionalProperties: false
      required:
        [
          id,
          name,
          description,
          targetAmountMinor,
          currentAmountMinor,
          currentAmountCurrency,
          currency,
          targetDate,
          linkedAccount,
          icon,
          status,
          priority,
          assumedAnnualReturnBps,
          progressPercent,
          trackingStatus,
          valueIncomplete,
          missingCurrencies,
          plan,
          projection,
        ]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        description: { type: [string, "null"] }
        targetAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        currentAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        currentAmountCurrency: { type: string }
        currency: { type: string }
        targetDate: { type: string, format: date }
        linkedAccount:
          oneOf:
            - $ref: "#/components/schemas/GoalLinkedAccount"
            - type: "null"
        icon: { type: string }
        status: { type: string }
        priority: { type: integer, format: int32 }
        assumedAnnualReturnBps: { type: integer, format: int32 }
        progressPercent:
          $ref: "#/components/schemas/DecimalString"
        trackingStatus:
          type: string
          enum: [on_track, behind, incomplete]
        valueIncomplete: { type: boolean }
        missingCurrencies:
          type: array
          items: { type: string }
        plan:
          oneOf:
            - $ref: "#/components/schemas/GoalPlan"
            - type: "null"
        projection:
          type: array
          items:
            $ref: "#/components/schemas/GoalProjectionPoint"
        scenarios:
          oneOf:
            - $ref: "#/components/schemas/GoalScenarios"
            - type: "null"
    GoalScenarios:
      type: object
      additionalProperties: false
      required: [savedPlan, requiredPace, lowerReturn]
      properties:
        savedPlan: { $ref: "#/components/schemas/GoalScenario" }
        requiredPace: { $ref: "#/components/schemas/GoalScenario" }
        lowerReturn: { $ref: "#/components/schemas/GoalScenario" }
    GoalScenario:
      type: object
      additionalProperties: false
      required:
        [
          monthlyContributionMinor,
          annualReturnBps,
          projectedAtTargetMinor,
          projectedProgressPercent,
          newContributionsMinor,
          estimatedGrowthMinor,
          estimatedCompletion,
          reachesTarget,
        ]
      properties:
        monthlyContributionMinor: { $ref: "#/components/schemas/MinorUnits" }
        annualReturnBps: { type: integer, format: int32 }
        projectedAtTargetMinor: { $ref: "#/components/schemas/MinorUnits" }
        projectedProgressPercent: { $ref: "#/components/schemas/DecimalString" }
        newContributionsMinor: { $ref: "#/components/schemas/MinorUnits" }
        estimatedGrowthMinor: { $ref: "#/components/schemas/MinorUnits" }
        estimatedCompletion: { type: [string, "null"], format: date }
        reachesTarget: { type: boolean }
    GoalProjectionPoint:
      type: object
      additionalProperties: false
      required: [date, projectedMinor, contributionsMinor, targetMinor]
      properties:
        date: { type: string, format: date-time }
        projectedMinor:
          $ref: "#/components/schemas/MinorUnits"
        contributionsMinor:
          $ref: "#/components/schemas/MinorUnits"
        targetMinor:
          $ref: "#/components/schemas/MinorUnits"
    GoalMilestone:
      type: object
      additionalProperties: false
      required:
        [
          id,
          goalId,
          name,
          targetAmountMinor,
          targetDate,
          status,
          progressPercent,
          remainingMinor,
        ]
      properties:
        id: { type: string, format: uuid }
        goalId: { type: string, format: uuid }
        name: { type: string }
        targetAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        targetDate: { type: [string, "null"], format: date }
        status: { type: string }
        progressPercent:
          $ref: "#/components/schemas/DecimalString"
        remainingMinor:
          oneOf:
            - $ref: "#/components/schemas/MinorUnits"
            - type: "null"
    GoalAlert:
      type: object
      additionalProperties: false
      required:
        [
          goalId,
          goalName,
          currency,
          targetAmountMinor,
          currentAmountMinor,
          progressPercent,
          targetDate,
          alertKey,
          assumedAnnualReturnBps,
        ]
      properties:
        goalId: { type: string, format: uuid }
        goalName: { type: string }
        currency: { type: string }
        targetAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        currentAmountMinor:
          $ref: "#/components/schemas/MinorUnits"
        progressPercent:
          $ref: "#/components/schemas/DecimalString"
        targetDate: { type: string, format: date }
        alertKey: { type: string }
        assumedAnnualReturnBps: { type: integer, format: int32 }
    CurrentTotals:
      type: object
      additionalProperties: false
      required:
        [
          assets,
          liabilities,
          netWorth,
          liquid,
          investible,
          contributions,
          withdrawals,
          income,
          fees,
          capitalGrowth,
        ]
      properties:
        assets:
          $ref: "#/components/schemas/MinorUnits"
        liabilities:
          $ref: "#/components/schemas/MinorUnits"
        netWorth:
          $ref: "#/components/schemas/MinorUnits"
        liquid:
          $ref: "#/components/schemas/MinorUnits"
        investible:
          $ref: "#/components/schemas/MinorUnits"
        contributions:
          $ref: "#/components/schemas/MinorUnits"
        withdrawals:
          $ref: "#/components/schemas/MinorUnits"
        income:
          $ref: "#/components/schemas/MinorUnits"
        fees:
          $ref: "#/components/schemas/MinorUnits"
        capitalGrowth:
          $ref: "#/components/schemas/MinorUnits"
    HistoricalPoint:
      type: object
      additionalProperties: false
      required:
        [
          date,
          assetsMinor,
          liabilitiesMinor,
          netWorthMinor,
          liquidMinor,
          investibleMinor,
          complete,
          missingCurrencies,
        ]
      properties:
        date: { type: string, format: date-time }
        assetsMinor: { $ref: "#/components/schemas/MinorUnits" }
        liabilitiesMinor: { $ref: "#/components/schemas/MinorUnits" }
        netWorthMinor: { $ref: "#/components/schemas/MinorUnits" }
        liquidMinor: { $ref: "#/components/schemas/MinorUnits" }
        investibleMinor: { $ref: "#/components/schemas/MinorUnits" }
        complete: { type: boolean }
        missingCurrencies:
          type: array
          items: { type: string }
    Dashboard:
      type: object
      additionalProperties: false
      required:
        [
          asOf,
          baseCurrency,
          totals,
          accountCount,
          goalCount,
          currentComplete,
          missingCurrencies,
          historicalAvailable,
          historicalComplete,
          periodChanges,
          valueBasis,
          history,
          allocation,
          investibleAllocation,
          institutionAllocation,
          currencyAllocation,
          instrumentAllocation,
          compositionComplete,
          completenessReasons,
        ]
      properties:
        asOf: { type: string, format: date }
        baseCurrency: { type: string }
        totals:
          $ref: "#/components/schemas/CurrentTotals"
        accountCount: { type: integer, minimum: 0 }
        goalCount: { type: integer, minimum: 0 }
        currentComplete: { type: boolean }
        missingCurrencies:
          type: array
          items: { type: string }
        historicalAvailable: { type: boolean }
        historicalComplete: { type: boolean }
        periodChanges:
          $ref: "#/components/schemas/DashboardPeriodChanges"
        valueBasis: { type: string }
        history:
          type: array
          items: { $ref: "#/components/schemas/HistoricalPoint" }
        allocation:
          type: array
          items: { $ref: "#/components/schemas/AllocationItem" }
        investibleAllocation:
          type: array
          items: { $ref: "#/components/schemas/AllocationItem" }
        institutionAllocation:
          type: array
          items: { $ref: "#/components/schemas/AllocationItem" }
        currencyAllocation:
          type: array
          items: { $ref: "#/components/schemas/AllocationItem" }
        instrumentAllocation:
          type: array
          items: { $ref: "#/components/schemas/AllocationItem" }
        compositionComplete: { type: boolean }
        completenessReasons:
          type: array
          items: { type: string }
    DashboardPeriodChanges:
      type: object
      additionalProperties: false
      required: [oneMonth, threeMonths, oneYear, allTime]
      properties:
        oneMonth:
          anyOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
        threeMonths:
          anyOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
        oneYear:
          anyOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
        allTime:
          anyOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
    ReportSummary:
      type: object
      additionalProperties: false
      required:
        [
          asOf,
          baseCurrency,
          totals,
          accountCount,
          goalCount,
          currentComplete,
          missingCurrencies,
          valueBasis,
          history,
          historicalComplete,
          compositionComplete,
          completenessReasons,
        ]
      properties:
        asOf: { type: string, format: date }
        baseCurrency: { type: string }
        totals:
          $ref: "#/components/schemas/CurrentTotals"
        accountCount: { type: integer, minimum: 0 }
        goalCount: { type: integer, minimum: 0 }
        currentComplete: { type: boolean }
        missingCurrencies:
          type: array
          items: { type: string }
        valueBasis: { type: string }
        history:
          type: array
          items: { $ref: "#/components/schemas/HistoricalPoint" }
        historicalComplete: { type: boolean }
        compositionComplete: { type: boolean }
        completenessReasons:
          type: array
          items: { type: string }
    AllocationItem:
      type: object
      additionalProperties: false
      required: [name, valueMinor, sharePercent]
      properties:
        name: { type: string }
        valueMinor:
          $ref: "#/components/schemas/MinorUnits"
        sharePercent:
          $ref: "#/components/schemas/DecimalString"
    ReportAllocation:
      type: object
      additionalProperties: false
      required:
        [
          asOf,
          baseCurrency,
          currentComplete,
          missingCurrencies,
          valueBasis,
          categories,
          institutions,
          currencies,
          investibleCategories,
          instruments,
        ]
      properties:
        asOf: { type: string, format: date }
        baseCurrency: { type: string }
        currentComplete: { type: boolean }
        missingCurrencies:
          type: array
          items: { type: string }
        valueBasis: { type: string }
        categories:
          type: array
          items:
            $ref: "#/components/schemas/AllocationItem"
        institutions:
          type: array
          items:
            $ref: "#/components/schemas/AllocationItem"
        currencies:
          type: array
          items:
            $ref: "#/components/schemas/AllocationItem"
        investibleCategories:
          type: array
          items:
            $ref: "#/components/schemas/AllocationItem"
        instruments:
          type: array
          items:
            $ref: "#/components/schemas/AllocationItem"
    AccountHistoryPoint:
      type: object
      additionalProperties: false
      required: [date, valueMinor, complete]
      properties:
        date: { type: string, format: date }
        valueMinor: { $ref: "#/components/schemas/MinorUnits" }
        complete: { type: boolean }
    AccountAnalytics:
      type: object
      additionalProperties: false
      required:
        [
          accountId,
          currency,
          metrics,
          positionSummary,
          history,
          historyComplete,
          movementAttributionAvailable,
          movementAttribution,
          completenessReasons,
        ]
      properties:
        accountId: { type: string, format: uuid }
        currency: { type: string }
        metrics:
          $ref: "#/components/schemas/AccountFlowMetrics"
        positionSummary:
          oneOf:
            - $ref: "#/components/schemas/AccountPositionSummary"
            - type: "null"
        history:
          type: array
          items: { $ref: "#/components/schemas/AccountHistoryPoint" }
        historyComplete: { type: boolean }
        movementAttributionAvailable: { type: boolean }
        movementAttribution:
          oneOf:
            - $ref: "#/components/schemas/PositionMovementAttribution"
            - type: "null"
        completenessReasons:
          type: array
          items: { type: string }
    AccountFlowMetrics:
      type: object
      additionalProperties: false
      required:
        [
          contributionsMinor,
          withdrawalsMinor,
          incomeMinor,
          feesMinor,
          capitalGrowthMinor,
          estimatedGainMinor,
        ]
      properties:
        contributionsMinor: { $ref: "#/components/schemas/MinorUnits" }
        withdrawalsMinor: { $ref: "#/components/schemas/MinorUnits" }
        incomeMinor: { $ref: "#/components/schemas/MinorUnits" }
        feesMinor: { $ref: "#/components/schemas/MinorUnits" }
        capitalGrowthMinor: { $ref: "#/components/schemas/MinorUnits" }
        estimatedGainMinor: { $ref: "#/components/schemas/MinorUnits" }
    AccountPositionSummary:
      type: object
      additionalProperties: false
      required: [cashMinor, positionsMinor, complete, positions]
      properties:
        cashMinor: { $ref: "#/components/schemas/MinorUnits" }
        positionsMinor: { $ref: "#/components/schemas/MinorUnits" }
        complete: { type: boolean }
        positions:
          type: array
          items: { $ref: "#/components/schemas/AccountPosition" }
    AccountPosition:
      type: object
      additionalProperties: false
      required:
        [instrumentId, instrumentName, instrumentSymbol, quoteCurrency, instrumentArchived, quantity, unitPrice, priceDate, priceSource, valueMinor, complete, stale]
      properties:
        instrumentId: { type: string, format: uuid }
        instrumentName: { type: string }
        instrumentSymbol: { type: string }
        quoteCurrency: { type: string }
        instrumentArchived: { type: boolean }
        quantity: { $ref: "#/components/schemas/DecimalString" }
        unitPrice:
          oneOf:
            - { $ref: "#/components/schemas/DecimalString" }
            - { type: "null" }
        priceDate: { type: [string, "null"], format: date }
        priceSource: { type: string }
        valueMinor:
          oneOf:
            - { $ref: "#/components/schemas/MinorUnits" }
            - { type: "null" }
        complete: { type: boolean }
        stale: { type: boolean }
    PositionMovementAttribution:
      type: object
      additionalProperties: false
      required:
        [
          from,
          to,
          startValueMinor,
          endValueMinor,
          changeMinor,
          externalCashMinor,
          incomeMinor,
          feesMinor,
          cashAdjustmentsMinor,
          internalTradeCashMinor,
          quantityMovementMinor,
          priceMovementMinor,
          currencyMovementMinor,
          unattributedMinor,
          complete,
          methodology,
          returnStatus,
          returnMessage,
        ]
      properties:
        from: { type: string, format: date-time }
        to: { type: string, format: date-time }
        startValueMinor: { $ref: "#/components/schemas/MinorUnits" }
        endValueMinor: { $ref: "#/components/schemas/MinorUnits" }
        changeMinor: { $ref: "#/components/schemas/MinorUnits" }
        externalCashMinor: { $ref: "#/components/schemas/MinorUnits" }
        incomeMinor: { $ref: "#/components/schemas/MinorUnits" }
        feesMinor: { $ref: "#/components/schemas/MinorUnits" }
        cashAdjustmentsMinor: { $ref: "#/components/schemas/MinorUnits" }
        internalTradeCashMinor: { $ref: "#/components/schemas/MinorUnits" }
        quantityMovementMinor: { $ref: "#/components/schemas/MinorUnits" }
        priceMovementMinor: { $ref: "#/components/schemas/MinorUnits" }
        currencyMovementMinor: { $ref: "#/components/schemas/MinorUnits" }
        unattributedMinor: { $ref: "#/components/schemas/MinorUnits" }
        complete: { type: boolean }
        methodology: { type: string, const: position_bridge_v1 }
        returnStatus: { type: string, const: unavailable }
        returnMessage: { type: string }
    SettingsRead:
      type: object
      additionalProperties: false
      required: [settings, currencyConfiguration, exchangeRates, authMethods]
      properties:
        settings:
          $ref: "#/components/schemas/UserSettings"
        currencyConfiguration:
          $ref: "#/components/schemas/CurrencyConfiguration"
        exchangeRates:
          type: array
          items:
            $ref: "#/components/schemas/ExchangeRate"
        authMethods:
          $ref: "#/components/schemas/AuthMethodState"
    UserSettings:
      type: object
      additionalProperties: false
      required:
        [
          displayName,
          appName,
          baseCurrency,
          supportedCurrencies,
          timezone,
          preferredDateFormat,
          defaultDashboardPeriod,
          sessionTimeoutMinutes,
          defaultGoalReturnBps,
          positionStaleDaysStock,
          positionStaleDaysEtf,
          positionStaleDaysFund,
          createdAt,
          updatedAt,
        ]
      properties:
        displayName: { type: string }
        appName: { type: string }
        baseCurrency: { type: string }
        supportedCurrencies:
          type: array
          items: { type: string }
        timezone: { type: string }
        preferredDateFormat: { type: string }
        defaultDashboardPeriod: { type: string }
        sessionTimeoutMinutes: { type: integer, format: int32 }
        defaultGoalReturnBps: { type: integer, format: int32 }
        positionStaleDaysStock: { type: integer, format: int32 }
        positionStaleDaysEtf: { type: integer, format: int32 }
        positionStaleDaysFund: { type: integer, format: int32 }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    CurrencyConfiguration:
      type: object
      additionalProperties: false
      required: [baseCurrency, enabledCurrencies, referencedCurrencies]
      properties:
        baseCurrency: { type: string }
        enabledCurrencies:
          type: array
          items: { type: string }
        referencedCurrencies:
          type: array
          items: { type: string }
    ExchangeRate:
      type: object
      additionalProperties: false
      required:
        [
          id,
          baseCurrency,
          quoteCurrency,
          rate,
          effectiveDate,
          source,
          createdAt,
        ]
      properties:
        id: { type: string, format: uuid }
        baseCurrency: { type: string }
        quoteCurrency: { type: string }
        rate:
          $ref: "#/components/schemas/DecimalString"
        effectiveDate: { type: string, format: date-time }
        source: { type: string }
        createdAt: { type: string, format: date-time }
    AuthMethodState:
      type: object
      additionalProperties: false
      required: [status, hasPassword, oidcIdentities]
      properties:
        status: { type: string }
        hasPassword: { type: boolean }
        oidcIdentities:
          type: array
          items:
            $ref: "#/components/schemas/OIDCIdentity"
    OIDCIdentity:
      type: object
      additionalProperties: false
      required: [id, issuer, createdAt, updatedAt, lastLoginAt]
      properties:
        id: { type: string, format: uuid }
        issuer: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        lastLoginAt: { type: string, format: date-time }
    SecurityPrice:
      type: object
      additionalProperties: false
      required:
        [
          id,
          externalId,
          price,
          currency,
          effectiveDate,
          source,
          provenance,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        externalId: { type: [string, "null"] }
        price:
          $ref: "#/components/schemas/DecimalString"
        currency: { type: string }
        effectiveDate: { type: string, format: date-time }
        source: { type: string }
        provenance: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    Instrument:
      type: object
      additionalProperties: false
      required:
        [
          id,
          externalId,
          name,
          symbol,
          identifierType,
          identifier,
          exchangeMic,
          assetType,
          quoteCurrency,
          archivedAt,
          createdAt,
          updatedAt,
          latestPrice,
        ]
      properties:
        id: { type: string, format: uuid }
        externalId: { type: [string, "null"] }
        name: { type: string }
        symbol: { type: [string, "null"] }
        identifierType: { type: string }
        identifier: { type: [string, "null"] }
        exchangeMic: { type: [string, "null"] }
        assetType: { type: string }
        quoteCurrency: { type: string }
        archivedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        latestPrice:
          oneOf:
            - $ref: "#/components/schemas/SecurityPrice"
            - type: "null"
    InstrumentDetail:
      type: object
      additionalProperties: false
      required: [instrument, prices]
      properties:
        instrument:
          $ref: "#/components/schemas/Instrument"
        prices:
          type: array
          items:
            $ref: "#/components/schemas/SecurityPrice"
    EstatePlanInput:
      type: object
      additionalProperties: false
      required: [title]
      properties:
        title: { type: string, minLength: 1, maxLength: 120 }
        jurisdiction: { type: string, maxLength: 120 }
        lastReviewedDate: { type: [string, "null"], format: date }
        reviewReminderDate: { type: [string, "null"], format: date }
    BeneficiaryInput:
      type: object
      additionalProperties: false
      required: [kind, name]
      properties:
        kind: { type: string, enum: [person, organization, trust] }
        name: { type: string, minLength: 1, maxLength: 120 }
        relationship: { type: string, maxLength: 80 }
        contactSummary: { type: string, maxLength: 300 }
        notes: { type: string, maxLength: 2000 }
    EstateDirectiveInput:
      type: object
      additionalProperties: false
      required:
        [isIncluded, ownershipShareBps, transferContext, distributionMethod]
      properties:
        isIncluded: { type: boolean }
        ownershipShareBps:
          { type: integer, format: int32, minimum: 1, maximum: 10000 }
        transferContext:
          {
            type: string,
            enum:
              [
                estate,
                joint_survivorship,
                provider_designation,
                trust_entity,
                unknown,
              ],
          }
        distributionMethod:
          {
            type: string,
            enum: [transfer_asset, sell_and_divide, cash_equivalent, undecided],
          }
        documentReference: { type: string, maxLength: 300 }
        notes: { type: string, maxLength: 2000 }
        reviewedAt: { type: [string, "null"], format: date }
    EstateAllocationInput:
      type: object
      additionalProperties: false
      required: [beneficiaryId, tier, allocationBps]
      properties:
        beneficiaryId: { type: string, format: uuid }
        tier: { type: string, enum: [primary, contingent] }
        allocationBps:
          { type: integer, format: int32, minimum: 1, maximum: 10000 }
        notes: { type: string, maxLength: 2000 }
    EstatePlan:
      type: object
      additionalProperties: false
      required:
        [
          id,
          title,
          jurisdiction,
          lastReviewedDate,
          reviewReminderDate,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        title: { type: string }
        jurisdiction: { type: [string, "null"] }
        lastReviewedDate: { type: [string, "null"], format: date-time }
        reviewReminderDate: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    Beneficiary:
      type: object
      additionalProperties: false
      required:
        [
          id,
          kind,
          name,
          relationship,
          contactSummary,
          notes,
          archivedAt,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        kind: { type: string, enum: [person, organization, trust] }
        name: { type: string }
        relationship: { type: [string, "null"] }
        contactSummary: { type: [string, "null"] }
        notes: { type: [string, "null"] }
        archivedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    EstateDirective:
      type: object
      additionalProperties: false
      required:
        [
          id,
          estatePlanId,
          accountId,
          accountName,
          currency,
          currentValueMinor,
          isLiability,
          accountArchivedAt,
          isIncluded,
          ownershipShareBps,
          transferContext,
          distributionMethod,
          documentReference,
          notes,
          reviewedAt,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        estatePlanId: { type: string, format: uuid }
        accountId: { type: string, format: uuid }
        accountName: { type: string }
        currency: { type: string }
        currentValueMinor:
          $ref: "#/components/schemas/MinorUnits"
        isLiability: { type: boolean }
        accountArchivedAt: { type: [string, "null"], format: date-time }
        isIncluded: { type: boolean }
        ownershipShareBps:
          { type: integer, format: int32, minimum: 1, maximum: 10000 }
        transferContext:
          {
            type: string,
            enum:
              [
                estate,
                joint_survivorship,
                provider_designation,
                trust_entity,
                unknown,
              ],
          }
        distributionMethod:
          {
            type: string,
            enum: [transfer_asset, sell_and_divide, cash_equivalent, undecided],
          }
        documentReference: { type: [string, "null"] }
        notes: { type: [string, "null"] }
        reviewedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    EstateAllocation:
      type: object
      additionalProperties: false
      required:
        [
          id,
          estatePlanId,
          directiveId,
          beneficiaryId,
          tier,
          allocationBps,
          notes,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        estatePlanId: { type: string, format: uuid }
        directiveId: { type: string, format: uuid }
        beneficiaryId: { type: string, format: uuid }
        tier: { type: string, enum: [primary, contingent] }
        allocationBps:
          { type: integer, format: int32, minimum: 1, maximum: 10000 }
        notes: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    ResiduaryAllocation:
      type: object
      additionalProperties: false
      required:
        [
          id,
          estatePlanId,
          beneficiaryId,
          tier,
          allocationBps,
          notes,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        estatePlanId: { type: string, format: uuid }
        beneficiaryId: { type: string, format: uuid }
        tier: { type: string, enum: [primary, contingent] }
        allocationBps:
          { type: integer, format: int32, minimum: 1, maximum: 10000 }
        notes: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    EstateSnapshotMeta:
      type: object
      additionalProperties: false
      required:
        [
          id,
          estatePlanId,
          version,
          title,
          valueAsOfDate,
          baseCurrency,
          contentHash,
          generatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        estatePlanId: { type: string, format: uuid }
        version: { type: integer, format: int32 }
        title: { type: string }
        valueAsOfDate: { type: string, format: date-time }
        baseCurrency: { type: string }
        contentHash: { type: string }
        generatedAt: { type: string, format: date-time }
    EstateSnapshot:
      type: object
      additionalProperties: false
      required:
        [
          id,
          estatePlanId,
          version,
          title,
          valueAsOfDate,
          baseCurrency,
          contentHash,
          generatedAt,
          content,
        ]
      properties:
        id: { type: string, format: uuid }
        estatePlanId: { type: string, format: uuid }
        version: { type: integer, format: int32 }
        title: { type: string }
        valueAsOfDate: { type: string, format: date-time }
        baseCurrency: { type: string }
        contentHash: { type: string }
        generatedAt: { type: string, format: date-time }
        content: {}
    EstateWorkspace:
      type: object
      additionalProperties: false
      required:
        [
          plan,
          beneficiaries,
          directives,
          allocations,
          residuaryAllocations,
          snapshots,
          currentValuesComplete,
          currentValuesWarning,
        ]
      properties:
        plan:
          oneOf:
            - $ref: "#/components/schemas/EstatePlan"
            - type: "null"
        beneficiaries:
          type: array
          items:
            $ref: "#/components/schemas/Beneficiary"
        directives:
          type: array
          items:
            $ref: "#/components/schemas/EstateDirective"
        allocations:
          type: array
          items:
            $ref: "#/components/schemas/EstateAllocation"
        residuaryAllocations:
          type: array
          items:
            $ref: "#/components/schemas/ResiduaryAllocation"
        snapshots:
          type: array
          items:
            $ref: "#/components/schemas/EstateSnapshotMeta"
        currentValuesComplete: { type: boolean }
        currentValuesWarning: { type: string }
    AIProviderSettings:
      type: object
      additionalProperties: false
      required:
        [
          provider,
          baseUrl,
          model,
          hasStoredApiKey,
          apiKeyHint,
          includeExactAmounts,
          includeAccountNames,
          monthlyTokenLimit,
          maxOutputTokens,
          createdAt,
          updatedAt,
        ]
      properties:
        provider: { type: string }
        baseUrl: { type: string }
        model: { type: string }
        hasStoredApiKey: { type: boolean }
        apiKeyHint: { type: [string, "null"] }
        includeExactAmounts: { type: boolean }
        includeAccountNames: { type: boolean }
        monthlyTokenLimit: { type: integer, format: int32 }
        maxOutputTokens: { type: integer, format: int32 }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    AIUsageEvent:
      type: object
      additionalProperties: false
      required:
        [
          id,
          provider,
          endpointHost,
          model,
          requestType,
          status,
          billingMonth,
          chargedTokens,
          inputTokens,
          outputTokens,
          latencyMs,
          errorCode,
          createdAt,
          updatedAt,
        ]
      properties:
        id: { type: string, format: uuid }
        provider: { type: string }
        endpointHost: { type: string }
        model: { type: string }
        requestType: { type: string }
        status: { type: string }
        billingMonth: { type: string, pattern: "^[0-9]{4}-[0-9]{2}$" }
        chargedTokens: { type: integer, format: int32 }
        inputTokens: { type: [integer, "null"], format: int32 }
        outputTokens: { type: [integer, "null"], format: int32 }
        latencyMs: { type: [integer, "null"], format: int32 }
        errorCode: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    AIUsageSummary:
      type: object
      additionalProperties: false
      required:
        [
          billingMonth,
          chargedTokens,
          remainingTokens,
          monthlyTokenLimit,
          successfulReviews,
          lastUsedAt,
        ]
      properties:
        billingMonth: { type: string, pattern: "^[0-9]{4}-[0-9]{2}$" }
        chargedTokens: { type: integer, format: int64 }
        remainingTokens: { type: integer, format: int64 }
        monthlyTokenLimit: { type: integer, format: int32 }
        successfulReviews: { type: integer, minimum: 0 }
        lastUsedAt: { type: [string, "null"], format: date-time }
    ReviewAvailability:
      type: object
      additionalProperties: false
      required:
        [
          available,
          reason,
          providerConfigured,
          storedCredentialAvailable,
          sessionCredentialAccepted,
          cooldownUntil,
          budgetRemainingTokens,
        ]
      properties:
        available: { type: boolean }
        reason: { type: string }
        providerConfigured: { type: boolean }
        storedCredentialAvailable: { type: boolean }
        sessionCredentialAccepted: { type: boolean }
        cooldownUntil: { type: [string, "null"], format: date-time }
        budgetRemainingTokens: { type: integer, format: int64 }
    AIRead:
      type: object
      additionalProperties: false
      required: [settings, usage, events, reviewAvailability]
      properties:
        settings:
          oneOf:
            - $ref: "#/components/schemas/AIProviderSettings"
            - type: "null"
        usage:
          $ref: "#/components/schemas/AIUsageSummary"
        events:
          type: array
          items:
            $ref: "#/components/schemas/AIUsageEvent"
        reviewAvailability:
          $ref: "#/components/schemas/ReviewAvailability"
    AIProvider:
      type: string
      enum: [openai, anthropic, deepseek]
    AISettingsInput:
      type: object
      additionalProperties: false
      required:
        [
          provider,
          model,
          includeExactAmounts,
          includeAccountNames,
          monthlyTokenLimit,
          maxOutputTokens,
        ]
      properties:
        provider: { $ref: "#/components/schemas/AIProvider" }
        model:
          {
            type: string,
            minLength: 1,
            maxLength: 200,
            pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
            description: "Provider model identifier: a suggested model or any other model the provider serves.",
          }
        includeExactAmounts:
          {
            type: boolean,
            description: Whether exact financial amounts may be shared with the configured provider.,
          }
        includeAccountNames:
          {
            type: boolean,
            description: Whether private account names may be shared with the configured provider.,
          }
        monthlyTokenLimit: { type: integer, minimum: 10000, maximum: 100000000 }
        maxOutputTokens:
          {
            type: integer,
            minimum: 256,
            description: Must not exceed `monthlyTokenLimit`.,
          }
    AIWorkflowSettings:
      type: object
      additionalProperties: false
      required:
        [
          provider,
          baseUrl,
          model,
          includeExactAmounts,
          includeAccountNames,
          monthlyTokenLimit,
          maxOutputTokens,
          hasStoredApiKey,
          apiKeyHint,
          updatedAt,
        ]
      properties:
        provider: { $ref: "#/components/schemas/AIProvider" }
        baseUrl:
          {
            type: string,
            format: uri,
            description: Fixed provider API endpoint derived from `provider`; read-only.,
          }
        model: { type: string }
        includeExactAmounts: { type: boolean }
        includeAccountNames: { type: boolean }
        monthlyTokenLimit: { type: integer }
        maxOutputTokens: { type: integer }
        hasStoredApiKey: { type: boolean }
        apiKeyHint:
          {
            type: [string, "null"],
            description: Non-secret credential hint; plaintext and ciphertext are never returned.,
          }
        updatedAt: { type: string, format: date-time }
    AICredentialInput:
      type: object
      additionalProperties: false
      required: [apiKey]
      properties:
        apiKey: { type: string, minLength: 1, maxLength: 4096, writeOnly: true }
    AIClearUsageResult:
      type: object
      additionalProperties: false
      required: [deleted]
      properties:
        deleted: { type: integer, format: int64, minimum: 0 }
    AIReviewPeriod:
      type: string
      enum: [1m, 3m, 6m, 1y, all]
    AIReviewFocus:
      type: string
      enum: [overall, allocation, goals, cash-flow, data-quality]
    AIReviewSnapshot:
      type: object
      additionalProperties: false
      required:
        [
          schemaVersion,
          asOf,
          period,
          focus,
          baseCurrency,
          sharing,
          completeness,
          portfolio,
          allocations,
          topAccounts,
          cashFlow,
          goals,
          dataQuality,
          methodology,
        ]
      properties:
        schemaVersion: { type: integer, const: 1 }
        asOf: { type: string, minLength: 1 }
        period: { $ref: "#/components/schemas/AIReviewPeriod" }
        focus: { $ref: "#/components/schemas/AIReviewFocus" }
        baseCurrency: { $ref: "#/components/schemas/CurrencyCode" }
        sharing: { type: object, additionalProperties: true }
        completeness: { type: object, additionalProperties: true }
        portfolio: { type: object, additionalProperties: true }
        allocations: { type: [object, array] }
        topAccounts: { type: array, items: {} }
        cashFlow: { type: object, additionalProperties: true }
        goals: { type: array, items: {} }
        dataQuality: { type: [object, array] }
        methodology: { type: object, additionalProperties: true }
    AIReviewRequest:
      type: object
      additionalProperties: false
      required:
        [period, focus, includeExactAmounts, includeAccountNames, snapshot]
      properties:
        period: { $ref: "#/components/schemas/AIReviewPeriod" }
        focus: { $ref: "#/components/schemas/AIReviewFocus" }
        includeExactAmounts: { type: boolean }
        includeAccountNames: { type: boolean }
        apiKey:
          {
            type: string,
            minLength: 8,
            maxLength: 4096,
            writeOnly: true,
            description: Ephemeral provider key; used only when no stored credential is selected.,
          }
        snapshot: { $ref: "#/components/schemas/AIReviewSnapshot" }
    AIReviewFinding:
      type: object
      additionalProperties: false
      required:
        [id, category, severity, confidence, title, explanation, evidenceRefs]
      properties:
        id: { type: string, minLength: 1, maxLength: 80 }
        category:
          {
            type: string,
            enum:
              [data-quality, allocation, liquidity, cash-flow, goals, general],
          }
        severity: { type: string, enum: [info, attention, high] }
        confidence: { type: string, enum: [low, medium, high] }
        title: { type: string, minLength: 1, maxLength: 140 }
        explanation: { type: string, minLength: 1, maxLength: 700 }
        evidenceRefs:
          { type: array, minItems: 1, maxItems: 6, items: { type: string } }
    AIReview:
      type: object
      additionalProperties: false
      required:
        [
          schemaVersion,
          headline,
          executiveSummary,
          dataQuality,
          strengths,
          attentionItems,
          goalObservations,
          questions,
          possibleNextChecks,
          limitations,
        ]
      properties:
        schemaVersion: { type: integer, const: 1 }
        headline: { type: string, minLength: 1, maxLength: 160 }
        executiveSummary: { type: string, minLength: 1, maxLength: 1400 }
        dataQuality:
          {
            type: array,
            maxItems: 6,
            items: { $ref: "#/components/schemas/AIReviewFinding" },
          }
        strengths:
          {
            type: array,
            maxItems: 6,
            items: { $ref: "#/components/schemas/AIReviewFinding" },
          }
        attentionItems:
          {
            type: array,
            maxItems: 8,
            items: { $ref: "#/components/schemas/AIReviewFinding" },
          }
        goalObservations:
          {
            type: array,
            maxItems: 6,
            items: { $ref: "#/components/schemas/AIReviewFinding" },
          }
        questions:
          { type: array, maxItems: 6, items: { type: string, maxLength: 300 } }
        possibleNextChecks:
          { type: array, maxItems: 6, items: { type: string, maxLength: 300 } }
        limitations:
          {
            type: array,
            minItems: 1,
            maxItems: 8,
            items: { type: string, minLength: 1, maxLength: 300 },
          }
    AIReviewResult:
      type: object
      additionalProperties: false
      required: [review, snapshot, provider, usage, generatedAt]
      properties:
        review: { $ref: "#/components/schemas/AIReview" }
        snapshot: { $ref: "#/components/schemas/AIReviewSnapshot" }
        provider:
          type: object
          additionalProperties: false
          required: [name, host, model]
          properties:
            name: { $ref: "#/components/schemas/AIProvider" }
            host: { type: string }
            model: { type: string }
        usage:
          type: object
          additionalProperties: false
          required: [inputTokens, outputTokens]
          properties:
            inputTokens: { type: [integer, "null"] }
            outputTokens: { type: [integer, "null"] }
        generatedAt: { type: string, format: date-time }
    AISourceUnit:
      type: object
      additionalProperties: false
      required: [id, location, text]
      properties:
        id: { type: string, pattern: "^source-[0-9]+$" }
        location: { type: string, minLength: 1, maxLength: 200 }
        text: { type: string, minLength: 1, maxLength: 65536 }
    AISource:
      type: object
      description: Text sections extracted from a source file in the browser. Wealthboard never receives the original file.
      additionalProperties: false
      required: [units, warnings]
      properties:
        units:
          {
            type: array,
            minItems: 1,
            maxItems: 1000,
            items: { $ref: "#/components/schemas/AISourceUnit" },
          }
        warnings: { type: array, maxItems: 100, items: { type: string } }
    AIConversionRequest:
      type: object
      additionalProperties: false
      required: [source, configurationHash, consent, trackingMode, currency]
      properties:
        source: { $ref: "#/components/schemas/AISource" }
        configurationHash: { type: string, pattern: "^[a-f0-9]{64}$" }
        consent: { type: boolean, const: true }
        apiKey: { type: string, minLength: 8, maxLength: 4096, writeOnly: true }
        trackingMode: { type: string, enum: [balance, positions] }
        currency: { $ref: "#/components/schemas/CurrencyCode" }
    AIDraftReference:
      type: object
      additionalProperties: false
      required: [collection, row, sourceIds]
      properties:
        collection: { type: string }
        row: { type: integer, minimum: 1 }
        sourceIds:
          {
            type: array,
            minItems: 1,
            items: { type: string, pattern: "^source-[0-9]+$" },
          }
    AIExclusion:
      type: object
      additionalProperties: false
      required: [sourceId, reason]
      properties:
        sourceId: { type: string, pattern: "^source-[0-9]+$" }
        reason: { type: string }
    AIConversionDraft:
      type: object
      additionalProperties: false
      required: [content, references, exclusions, issues]
      properties:
        content:
          {
            type: string,
            description: Generated Wealthboard import document content.,
          }
        references:
          {
            type: array,
            items: { $ref: "#/components/schemas/AIDraftReference" },
          }
        exclusions:
          { type: array, items: { $ref: "#/components/schemas/AIExclusion" } }
        issues: { type: array, maxItems: 100, items: { type: string } }
    Problem:
      type: object
      additionalProperties: false
      required: [type, title, status, detail]
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
    APIKeyScope:
      type: string
      enum:
        - portfolio:read
        - portfolio:write
        - imports:write
        - exports:read
        - ai:invoke
    APIKeyMetadata:
      type: object
      additionalProperties: false
      required: [id, name, prefix, scopes, createdAt]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        prefix:
          type: string
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/APIKeyScope"
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: [string, "null"]
          format: date-time
        lastUsedAt:
          type: [string, "null"]
          format: date-time
        revokedAt:
          type: [string, "null"]
          format: date-time
    CreateAPIKeyRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          default: [portfolio:read]
          items:
            $ref: "#/components/schemas/APIKeyScope"
        expiresAt:
          type: [string, "null"]
          format: date-time
    LoginRequest:
      type: object
      additionalProperties: false
      required: [username, password]
      properties:
        username:
          type: string
          pattern: "^[a-z0-9._-]{3,32}$"
        password:
          type: string
          minLength: 1
          maxLength: 256
    SignupRequest:
      type: object
      additionalProperties: false
      required: [username, displayName, password, confirmPassword]
      properties:
        username:
          type: string
          pattern: "^[a-z0-9._-]{3,32}$"
        displayName:
          type: string
          minLength: 1
          maxLength: 80
        baseCurrency:
          type: string
          pattern: "^[A-Z]{3}$"
          default: KES
        password:
          type: string
          minLength: 12
          maxLength: 256
        confirmPassword:
          type: string
          minLength: 12
          maxLength: 256
    SessionResponse:
      type: object
      additionalProperties: false
      required: [user, csrfToken]
      properties:
        user:
          type: object
          additionalProperties: false
          required: [id, username]
          properties:
            id:
              type: string
              format: uuid
            username:
              type: string
        csrfToken:
          type: string
    ChangePasswordRequest:
      type: object
      additionalProperties: false
      required: [currentPassword, newPassword, confirmPassword]
      properties:
        currentPassword:
          type: string
          minLength: 1
          maxLength: 256
        newPassword:
          type: string
          minLength: 12
          maxLength: 256
        confirmPassword:
          type: string
          minLength: 12
          maxLength: 256
    PasswordConfirmationRequest:
      type: object
      additionalProperties: false
      required: [currentPassword]
      properties:
        currentPassword:
          type: string
          minLength: 1
          maxLength: 256
    OidcLinkRequest:
      type: object
      additionalProperties: false
      required: [currentPassword]
      properties:
        currentPassword:
          type: string
          minLength: 1
          maxLength: 256
        next:
          type: string
          default: /settings
    EnableLocalCredentialRequest:
      type: object
      additionalProperties: false
      required: [username, password, confirmPassword]
      properties:
        username:
          type: string
          pattern: "^[a-z0-9._-]{3,32}$"
        password:
          type: string
          minLength: 12
          maxLength: 256
        confirmPassword:
          type: string
          minLength: 12
          maxLength: 256
  responses:
    CorporateActionCreated:
      description: Corporate-action event group created or an identical request replayed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EventGroupResponse"
    Problem:
      description: Request failed
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"