docs fix

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