reordered batch Inference endpoints (#1169)

* reordered batch endpts

* added sub-section

Author: SSharma-10

specification/DigitalOcean-public.v2.yaml

@@ -646,6 +646,12 @@ tags:
       synchronous APIs, making it a cost-effective choice for non-interactive
       workloads.
 
+  - name: Additional Batch Inference Helper APIs
+    description: |-
+      Helper operations for managing Batch Inference jobs — list all
+      submitted jobs and cancel a job that has not yet reached a terminal
+      state.
+
 
 x-tagGroups:
   - name: Public APIs
@@ -706,6 +712,7 @@ x-tagGroups:
       - Inference Introduction
       - Agent Inference
       - Batch Inference
+      - Additional Batch Inference Helper APIs
       - Embeddings
       - Serverless Inference
 
@@ -2996,23 +3003,23 @@ paths:
       $ref: 'resources/inference/inference_upload_batch_file.yml'
 
   /v1/batches:
-    get:
-      $ref: 'resources/inference/inference_list_batches.yml'
     post:
       $ref: 'resources/inference/inference_create_batch.yml'
+    get:
+      $ref: 'resources/inference/inference_list_batches.yml'
 
   /v1/batches/{batch_id}:
     get:
       $ref: 'resources/inference/inference_get_batch.yml'
 
-  /v1/batches/{batch_id}/cancel:
-    post:
-      $ref: 'resources/inference/inference_cancel_batch.yml'
-
   /v1/batches/{batch_id}/results:
     get:
       $ref: 'resources/inference/inference_get_batch_results.yml'
 
+  /v1/batches/{batch_id}/cancel:
+    post:
+      $ref: 'resources/inference/inference_cancel_batch.yml'
+
 components:
   securitySchemes:
     bearer_auth:

specification/resources/inference/inference_cancel_batch.yml

@@ -13,7 +13,7 @@ description: >
   Partial results produced before cancellation remain available via
   `GET /v1/batches/{batch_id}/results`.
 tags:
-  - Batch Inference
+  - Additional Batch Inference Helper APIs
 servers:
   - url: "https://inference.do-ai.run"
     description: production

specification/resources/inference/inference_list_batches.yml

@@ -5,7 +5,7 @@ description: >
   `limit` to control page size and `after` to page forward using the
   `last_id` from the previous response.
 tags:
-  - Batch Inference
+  - Additional Batch Inference Helper APIs
 servers:
   - url: "https://inference.do-ai.run"
     description: production

specification/resources/inference/models/batch.yml

@@ -110,17 +110,17 @@ properties:
     type: string
     format: date-time
     nullable: true
-    example: null
+    example: "2026-04-24T19:20:05Z"
   finalizing_at:
     type: string
     format: date-time
     nullable: true
-    example: null
+    example: "2026-04-24T20:10:42Z"
   completed_at:
     type: string
     format: date-time
     nullable: true
-    example: null
+    example: "2026-04-24T20:15:30Z"
   expires_at:
     type: string
     format: date-time
@@ -131,9 +131,9 @@ properties:
     type: string
     format: date-time
     nullable: true
-    example: null
+    example: "2026-04-24T19:45:11Z"
   failed_at:
     type: string
     format: date-time
     nullable: true
-    example: null
+    example: "2026-04-24T19:50:00Z"