feat: include retired flag for pool/drep_delegator endpoints

dostrelith678 · dostrelith678 · commit 885c93a4e8f3 · 2026-01-22T19:07:08.000Z
diff --git a/specs/results/koiosapi-guild.yaml b/specs/results/koiosapi-guild.yaml
@@ -1666,6 +1666,7 @@ paths:
         - Governance
       parameters:
         - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -1682,6 +1683,29 @@ paths:
       summary: DReps Delegators
       description: List of all delegators to requested delegated representative (DRep).
       operationId: drep_delegators
+  /drep_delegators_history: #RPC
+    get:
+      tags:
+        - Governance
+      parameters:
+        - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_epoch_no"
+      responses:
+        "200":
+          description: Success!!
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/drep_delegators"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: DReps Delegators History
+      description: List of all delegators to requested DRep for a given epoch - returns all epochs if not specified.
+      operationId: drep_delegators_history
   /committee_info: #RPC
     get:
       tags:
@@ -1901,6 +1925,7 @@ paths:
         - Pool
       parameters:
         - $ref: "#/components/parameters/_pool_bech32"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -2542,6 +2567,16 @@ components:
       in: query
       required: false
       allowEmptyValue: true
+    _include_retired:
+      deprecated: false
+      name: _include_retired
+      description: Include delegators for retired pools/dReps (default false returns empty for retired entities)
+      schema:
+        type: boolean
+      example: false
+      in: query
+      required: false
+      allowEmptyValue: true
     _pool_bech32:
       deprecated: false
       name: _pool_bech32
diff --git a/specs/results/koiosapi-mainnet.yaml b/specs/results/koiosapi-mainnet.yaml
@@ -1666,6 +1666,7 @@ paths:
         - Governance
       parameters:
         - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -1682,6 +1683,29 @@ paths:
       summary: DReps Delegators
       description: List of all delegators to requested delegated representative (DRep).
       operationId: drep_delegators
+  /drep_delegators_history: #RPC
+    get:
+      tags:
+        - Governance
+      parameters:
+        - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_epoch_no"
+      responses:
+        "200":
+          description: Success!!
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/drep_delegators"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: DReps Delegators History
+      description: List of all delegators to requested DRep for a given epoch - returns all epochs if not specified.
+      operationId: drep_delegators_history
   /committee_info: #RPC
     get:
       tags:
@@ -1901,6 +1925,7 @@ paths:
         - Pool
       parameters:
         - $ref: "#/components/parameters/_pool_bech32"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -2542,6 +2567,16 @@ components:
       in: query
       required: false
       allowEmptyValue: true
+    _include_retired:
+      deprecated: false
+      name: _include_retired
+      description: Include delegators for retired pools/dReps (default false returns empty for retired entities)
+      schema:
+        type: boolean
+      example: false
+      in: query
+      required: false
+      allowEmptyValue: true
     _pool_bech32:
       deprecated: false
       name: _pool_bech32
diff --git a/specs/results/koiosapi-preprod.yaml b/specs/results/koiosapi-preprod.yaml
@@ -1666,6 +1666,7 @@ paths:
         - Governance
       parameters:
         - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -1682,6 +1683,29 @@ paths:
       summary: DReps Delegators
       description: List of all delegators to requested delegated representative (DRep).
       operationId: drep_delegators
+  /drep_delegators_history: #RPC
+    get:
+      tags:
+        - Governance
+      parameters:
+        - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_epoch_no"
+      responses:
+        "200":
+          description: Success!!
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/drep_delegators"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: DReps Delegators History
+      description: List of all delegators to requested DRep for a given epoch - returns all epochs if not specified.
+      operationId: drep_delegators_history
   /committee_info: #RPC
     get:
       tags:
@@ -1901,6 +1925,7 @@ paths:
         - Pool
       parameters:
         - $ref: "#/components/parameters/_pool_bech32"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -2542,6 +2567,16 @@ components:
       in: query
       required: false
       allowEmptyValue: true
+    _include_retired:
+      deprecated: false
+      name: _include_retired
+      description: Include delegators for retired pools/dReps (default false returns empty for retired entities)
+      schema:
+        type: boolean
+      example: false
+      in: query
+      required: false
+      allowEmptyValue: true
     _pool_bech32:
       deprecated: false
       name: _pool_bech32
diff --git a/specs/results/koiosapi-preview.yaml b/specs/results/koiosapi-preview.yaml
@@ -1666,6 +1666,7 @@ paths:
         - Governance
       parameters:
         - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -1682,6 +1683,29 @@ paths:
       summary: DReps Delegators
       description: List of all delegators to requested delegated representative (DRep).
       operationId: drep_delegators
+  /drep_delegators_history: #RPC
+    get:
+      tags:
+        - Governance
+      parameters:
+        - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_epoch_no"
+      responses:
+        "200":
+          description: Success!!
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/drep_delegators"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: DReps Delegators History
+      description: List of all delegators to requested DRep for a given epoch - returns all epochs if not specified.
+      operationId: drep_delegators_history
   /committee_info: #RPC
     get:
       tags:
@@ -1901,6 +1925,7 @@ paths:
         - Pool
       parameters:
         - $ref: "#/components/parameters/_pool_bech32"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -2542,6 +2567,16 @@ components:
       in: query
       required: false
       allowEmptyValue: true
+    _include_retired:
+      deprecated: false
+      name: _include_retired
+      description: Include delegators for retired pools/dReps (default false returns empty for retired entities)
+      schema:
+        type: boolean
+      example: false
+      in: query
+      required: false
+      allowEmptyValue: true
     _pool_bech32:
       deprecated: false
       name: _pool_bech32
diff --git a/specs/templates/2-api-params.yaml b/specs/templates/2-api-params.yaml
@@ -149,6 +149,16 @@ parameters:
     in: query
     required: false
     allowEmptyValue: true
+  _include_retired:
+    deprecated: false
+    name: _include_retired
+    description: Include delegators for retired pools/dReps (default false returns empty for retired entities)
+    schema:
+      type: boolean
+    example: false
+    in: query
+    required: false
+    allowEmptyValue: true
   _pool_bech32:
     deprecated: false
     name: _pool_bech32
diff --git a/specs/templates/api-main.yaml b/specs/templates/api-main.yaml
@@ -1521,6 +1521,7 @@ paths:
         - Governance
       parameters:
         - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
@@ -1537,6 +1538,29 @@ paths:
       summary: DReps Delegators
       description: List of all delegators to requested delegated representative (DRep).
       operationId: drep_delegators
+  /drep_delegators_history: #RPC
+    get:
+      tags:
+        - Governance
+      parameters:
+        - $ref: "#/components/parameters/_drep_id"
+        - $ref: "#/components/parameters/_epoch_no"
+      responses:
+        "200":
+          description: Success!!
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/drep_delegators"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: DReps Delegators History
+      description: List of all delegators to requested DRep for a given epoch - returns all epochs if not specified.
+      operationId: drep_delegators_history
   /committee_info: #RPC
     get:
       tags:
@@ -1756,6 +1780,7 @@ paths:
         - Pool
       parameters:
         - $ref: "#/components/parameters/_pool_bech32"
+        - $ref: "#/components/parameters/_include_retired"
       responses:
         "200":
           description: Success!!
