docs fix

interface/api/accounts/auth_login.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Login using email/password and receive pending verification token
+  description: |
+    Validates account credentials and returns a short-lived `pendingToken`.
+    This endpoint does not return final access/refresh tokens; complete verification flow via `/verification/verify`.
   operationId: accountsLogin
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/LoginBody

interface/api/accounts/auth_refresh.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Refresh access token by refresh token
+  description: |
+    Validates refresh token + session identifiers and issues a new access token.
+    Use this endpoint when refresh token stays the same.
   operationId: accountsRefreshAccessToken
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody

interface/api/accounts/auth_rotate.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Accounts, Auth]
   summary: Rotate refresh token and issue new access/refresh tokens
+  description: |
+    Validates refresh token + session identifiers and returns a new token pair.
+    Use this endpoint when replacing both access and refresh tokens.
   operationId: accountsRotateRefreshToken
   requestBody:
     $ref: ./bodies/auth.yaml#/components/requestBodies/RefreshTokenBody

interface/api/organizations/get.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Organizations]
   summary: Get organization by reference
+  description: Fetches a single organization available to the authenticated account.
   operationId: organizationsGet
   security:
     - bearerAuth: []

interface/api/organizations/root.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Organizations]
   summary: List organizations of current account
+  description: Returns organizations the authenticated account can access.
   operationId: organizationsList
   security:
     - bearerAuth: []

interface/api/parameters/archived.yaml

@@ -4,5 +4,6 @@ components:
       name: archived
       in: query
       required: false
+      description: Filter by archive flag. `true` returns archived records, `false` returns active records.
       schema:
         type: boolean

interface/api/parameters/cascade.yaml

@@ -4,5 +4,6 @@ components:
       name: cascade
       in: query
       required: false
+      description: If `true`, apply operation to dependent objects where cascade is supported.
       schema:
         type: boolean

interface/api/parameters/cursor.yaml

@@ -4,5 +4,6 @@ components:
       name: cursor
       in: query
       required: false
+      description: Opaque cursor from a previous page response (`page.next_cursor`).
       schema:
         type: string

interface/api/parameters/destination_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: destination_ref
       in: query
       required: false
+      description: Optional destination endpoint reference filter (service-specific usage).
       schema:
         type: string

interface/api/parameters/filter_states.yaml

@@ -4,5 +4,8 @@ components:
       name: filter_states
       in: query
       required: false
+      description: |
+        Additional payment state filter. Accepts one value or comma-separated values.
+        Same semantics as `state`/`states`.
       schema:
         type: string

interface/api/parameters/limit.yaml

@@ -3,9 +3,9 @@ components:
     Limit:
       name: limit
       in: query
-      description: Max number of items to return.
+      description: Max number of items to return. Parsed as non-negative int64.
       required: false
       schema:
         type: integer
-        format: int32
+        format: int64
         minimum: 0

interface/api/parameters/offset.yaml

@@ -3,9 +3,9 @@ components:
     Offset:
       name: offset
       in: query
-      description: Number of items to skip.
+      description: Number of items to skip. Parsed as non-negative int64.
       required: false
       schema:
         type: integer
-        format: int32
+        format: int64
         minimum: 0

interface/api/parameters/org_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: org_ref
       in: path
       required: true
+      description: Organization reference in BFF route format (Mongo ObjectId, 24 hex chars).
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/organizations_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: organizations_ref
       in: path
       required: true
+      description: Organization reference used by payments/payment-methods/recipients routes.
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/payment_methods_ref.yaml

@@ -1,8 +1,9 @@
 components:
   parameters:
-    PaymentMethodsRef:
+    Payment MethodsRef:
       name: payment_methods_ref
       in: path
       required: true
+      description: Payment method reference (Mongo ObjectId, 24 hex chars).
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/recipients_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: recipients_ref
       in: path
       required: true
+      description: Recipient reference (Mongo ObjectId, 24 hex chars).
       schema:
         $ref: ../../models/objectid.yaml#/components/schemas/ObjectId

interface/api/parameters/source_ref.yaml

@@ -4,5 +4,6 @@ components:
       name: source_ref
       in: query
       required: false
+      description: Optional source endpoint reference filter (service-specific usage).
       schema:
         type: string

interface/api/parameters/state.yaml

@@ -4,5 +4,8 @@ components:
       name: state
       in: query
       required: false
+      description: |
+        Payment state filter. Accepts aliases like `accepted`, `settled`, `failed`
+        or canonical values like `orchestration_state_created`.
       schema:
         type: string

interface/api/parameters/states.yaml

@@ -4,5 +4,7 @@ components:
       name: states
       in: query
       required: false
+      description: |
+        Multi-state filter. Provide a comma-separated list with same accepted values as `state`.
       schema:
         type: string

interface/api/payment_methods/archive.yaml

@@ -1,15 +1,17 @@
 get:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Archive/unarchive payment method
+  description: Sets payment method archive state by `payment_methods_ref` and required `archived` query parameter.
   operationId: paymentMethodsArchive
   security:
     - bearerAuth: []
   parameters:
     - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
-    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/Payment MethodsRef
     - name: archived
       in: query
       required: true
+      description: Target archive value to set on the payment method.
       schema:
         type: boolean
     - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
@@ -24,7 +26,7 @@ get:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/create.yaml

@@ -1,6 +1,7 @@
 post:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Create payment method
+  description: Creates a payment method in the organization identified by `organizations_ref`.
   operationId: paymentMethodsCreate
   security:
     - bearerAuth: []
@@ -19,7 +20,7 @@ post:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/list.yaml

@@ -1,6 +1,9 @@
 get:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: List payment methods for recipient
+  description: |
+    Returns payment methods available for `recipients_ref` within `organizations_ref`.
+    Supports offset pagination and optional archive filtering.
   operationId: paymentMethodsList
   security:
     - bearerAuth: []
@@ -21,7 +24,7 @@ get:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/object.yaml

@@ -1,11 +1,12 @@
 get:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Get payment method
+  description: Returns payment method by `payment_methods_ref`.
   operationId: paymentMethodsGet
   security:
     - bearerAuth: []
   parameters:
-    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/Payment MethodsRef
   responses:
     '200':
       description: Payment method data
@@ -17,7 +18,7 @@ get:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':
@@ -30,13 +31,14 @@ get:
       $ref: ../response/operation.yaml#/components/responses/InternalServerError
 
 delete:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Delete payment method
+  description: Deletes payment method by reference. Use `cascade=true` to remove dependent objects when supported.
   operationId: paymentMethodsDelete
   security:
     - bearerAuth: []
   parameters:
-    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/PaymentMethodsRef
+    - $ref: ../parameters/payment_methods_ref.yaml#/components/parameters/Payment MethodsRef
     - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade
   responses:
     '200':
@@ -49,7 +51,7 @@ delete:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payment_methods/response/payment_method.yaml

@@ -1,6 +1,6 @@
 components:
   schemas:
-    PaymentMethodsAuthData:
+    Payment MethodsAuthData:
       type: object
       additionalProperties: false
       required:

interface/api/payment_methods/update.yaml

@@ -1,6 +1,7 @@
 put:
-  tags: [PaymentMethods]
+  tags: [Payment Methods]
   summary: Update payment method
+  description: Updates payment method fields from request payload.
   operationId: paymentMethodsUpdate
   security:
     - bearerAuth: []
@@ -17,7 +18,7 @@ put:
               - type: object
                 properties:
                   data:
-                    $ref: ./response/payment_method.yaml#/components/schemas/PaymentMethodsAuthData
+                    $ref: ./response/payment_method.yaml#/components/schemas/Payment MethodsAuthData
     '400':
       $ref: ../response/operation.yaml#/components/responses/BadRequest
     '401':

interface/api/payments/by_multiquote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Initiate payment batch by quote reference
+  description: Executes batch payment from a previously created multi-quote reference.
   operationId: paymentsInitiateBatchByQuote
   security:
     - bearerAuth: []

interface/api/payments/by_quote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Initiate payment using quote reference
+  description: Executes one payment from an existing quote reference (`quoteRef` required, `intent` forbidden).
   operationId: paymentsInitiateByQuote
   security:
     - bearerAuth: []

interface/api/payments/immediate.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Initiate payment from immediate intent
+  description: Creates quote and executes a single payment in one call (request must include `intent`).
   operationId: paymentsInitiateImmediate
   security:
     - bearerAuth: []

interface/api/payments/list.yaml

@@ -1,6 +1,9 @@
 get:
   tags: [Payments]
   summary: List payments in organization
+  description: |
+    Returns organization payments with cursor pagination and optional filters.
+    State filters accept aliases (`accepted`, `settled`, `failed`, etc.) or canonical orchestration states.
   operationId: paymentsList
   security:
     - bearerAuth: []
@@ -11,17 +14,20 @@ get:
     - name: quotation_ref
       in: query
       required: false
+      description: Filter by quotation reference used for execution.
       schema:
         type: string
     - name: created_from
       in: query
       required: false
+      description: Include payments created at or after this RFC3339 timestamp.
       schema:
         type: string
         format: date-time
     - name: created_to
       in: query
       required: false
+      description: Include payments created before this RFC3339 timestamp (must be after `created_from`).
       schema:
         type: string
         format: date-time

interface/api/payments/multiquote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Quote multiple payment intents
+  description: Calculates a batch quote for multiple payment intents in one request.
   operationId: paymentsMultiQuote
   security:
     - bearerAuth: []

interface/api/payments/quote.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Payments]
   summary: Quote single payment intent
+  description: Calculates quote for one payment intent without executing payment.
   operationId: paymentsQuote
   security:
     - bearerAuth: []

interface/api/payments/response/payment.yaml

@@ -31,9 +31,7 @@ components:
               type: string
             quoteRef:
               type: string
-            aggregate:
-              $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuoteAggregate
-            quotes:
+            items:
               type: array
               items:
                 $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
@@ -43,6 +41,7 @@ components:
       additionalProperties: false
       required:
         - accessToken
+        - payments
       properties:
         accessToken:
           $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData

interface/api/recipients/archive.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Recipients]
   summary: Archive/unarchive recipient
+  description: Sets recipient archive state by `recipients_ref` and required `archived` query parameter.
   operationId: recipientsArchive
   security:
     - bearerAuth: []
@@ -10,6 +11,7 @@ get:
     - name: archived
       in: query
       required: true
+      description: Target archive value to set on the recipient.
       schema:
         type: boolean
     - $ref: ../parameters/cascade.yaml#/components/parameters/Cascade

interface/api/recipients/create.yaml

@@ -1,6 +1,7 @@
 post:
   tags: [Recipients]
   summary: Create recipient
+  description: Creates a recipient inside the organization identified by `org_ref`.
   operationId: recipientsCreate
   security:
     - bearerAuth: []

interface/api/recipients/list.yaml

@@ -1,6 +1,9 @@
 get:
   tags: [Recipients]
   summary: List recipients
+  description: |
+    Returns recipients for the specified organization context.
+    Supports offset pagination and optional archive filtering.
   operationId: recipientsList
   security:
     - bearerAuth: []

interface/api/recipients/object.yaml

@@ -1,6 +1,7 @@
 get:
   tags: [Recipients]
   summary: Get recipient by reference
+  description: Returns a recipient by `recipients_ref`.
   operationId: recipientsGet
   security:
     - bearerAuth: []
@@ -32,6 +33,7 @@ get:
 delete:
   tags: [Recipients]
   summary: Delete recipient
+  description: Deletes recipient by reference. Use `cascade=true` to remove dependent objects when supported.
   operationId: recipientsDelete
   security:
     - bearerAuth: []

interface/api/recipients/update.yaml

@@ -1,6 +1,7 @@
 put:
   tags: [Recipients]
   summary: Update recipient
+  description: Updates recipient fields from request payload.
   operationId: recipientsUpdate
   security:
     - bearerAuth: []

interface/api/verification/create.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Verification, Auth]
   summary: Request verification code
+  description: |
+    Creates a verification challenge for the specified purpose/target.
+    For `purpose=login`, request must be authorized with a pending account token.
   operationId: verificationRequestCode
   security:
     - bearerAuth: []

interface/api/verification/request/verification.yaml

@@ -5,7 +5,6 @@ components:
       additionalProperties: false
       required:
         - purpose
-        - idempotencyKey
       properties:
         purpose:
           type: string

interface/api/verification/resend.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Verification, Auth]
   summary: Resend verification code
+  description: |
+    Re-issues a verification challenge using the same request shape as `/verification`.
+    Cooldown and retry limits are enforced by backend verification storage policy.
   operationId: verificationResendCode
   security:
     - bearerAuth: []

interface/api/verification/verify.yaml

@@ -1,6 +1,9 @@
 post:
   tags: [Verification, Auth]
   summary: Verify code and complete pending flow
+  description: |
+    Verifies submitted code and consumes verification token.
+    For login purpose, returns full auth payload (access + refresh tokens); for other purposes returns operation result.
   operationId: verificationVerifyCode
   security:
     - bearerAuth: []