HOST-2752: SLA API Documentation

api-reference/openapi/build.py

@@ -162,7 +162,7 @@ def build_master_doc():
                 "- `gpu_ram` in CLI = GB; in REST API = MB (CLI auto-converts)\n"
                 "- SSH keys must be registered BEFORE creating an instance (VM: no recovery; Docker: can add post-create)\n"
                 "- `onstart` field is limited to 4048 characters -- gzip+base64 for longer scripts\n"
-                "- `POST /api/v0/asks/{id}/` (create instance) returns `new_contract` as the instance ID, not `id`\n"
+                "- `PUT /api/v0/asks/{id}/` (create instance) returns `new_contract` as the instance ID, not `id`\n"
                 "- Poll trap: if `actual_status` becomes `exited`, `unknown`, or `offline` it will never reach `running` -- destroy and retry"
             ),
             'version': '1.0.0',

api-reference/openapi/yaml/cancel_maint.yaml

@@ -7,7 +7,7 @@ paths:
     put:
       summary: cancel maint
       description: |
-        Cancel a scheduled maintenance window for a specified machine.
+        Cancel every host-scheduled maintenance window on a machine. Vast-scheduled windows are left in place.
 
         CLI Usage: `vastai cancel maint <machine_id>`
       parameters:
@@ -39,6 +39,10 @@ paths:
                     type: string
                     example: deleted 1 scheduled maintenance window(s) on machine
                       1234
+                  admin_locked:
+                    type: integer
+                    description: Number of Vast-scheduled windows left in place.
+                    example: 0
         '404':
           description: Machine not found or does not belong to the user.
           content:

api-reference/openapi/yaml/create_instance.yaml

@@ -14,7 +14,7 @@ paths:
         Creates a new instance by accepting an "ask" contract from a provider.
 
         - Use the search offers endpoint to discover available machines.
-        - If `template_id` is provided, those template defaults are either merged or overridden by parameters specified in the request body.
+        - If `template_hash_id` is provided, those template defaults are either merged or overridden by parameters specified in the request body.
 
         **Template Precedence Rules:**
         - **Scalar fields** (image, disk, runtype, etc.): Request value overrides template value
@@ -23,7 +23,9 @@ paths:
 
         For detailed template usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).
 
-        CLI Usage: `vastai create instance <offer_id> <image> [options]`
+        **SLA note:** `target_reliability` is REST-only at rent time. The published CLI and SDK cannot pass this field until support ships. Use the web console or `PUT /api/v0/asks/{id}/` with `target_reliability` in the request body to enable SLA coverage — see [SLA Coverage](/guides/instances/choosing/sla-coverage).
+
+        CLI Usage: `vastai create instance <offer_id> --image <image> [options]` (no `target_reliability` flag today)
       security:
       - BearerAuth: []
       tags:
@@ -41,8 +43,11 @@ paths:
           application/json:
             schema:
               type: object
-              required: 
-              - image
+              description: |
+                Send `image`, `template_hash_id`, or both. When both are set, the request `image` overrides the template image.
+              anyOf:
+              - required: [image]
+              - required: [template_hash_id]
               properties:
                 image:
                   type: string
@@ -61,8 +66,20 @@ paths:
                 disk:
                   type: number
                   format: float
+                  minimum: 0
+                  description: >
+                    Disk size in GB. Omitted or 0 becomes 10 GB. Values from 1 through 7 are raised to 8 with no error. Send the same number you used as allocated_storage in search so the quoted price matches the bill.
+                target_reliability:
+                  type: number
+                  format: float
+                  minimum: 0
+                  maximum: 1
+                  exclusiveMaximum: true
                   description: |
-                    Size of local disk partition (in GB)
+                    0 or omitted means no SLA. A value in (0, 1) requests an SLA at that reliability target.
+                    Values below 0 or at least 1 return HTTP 400 `invalid_args`.
+                    `invalid_sla_params` covers an offer with no SLA, a target above the host commitment, or an SLA fee above 1× compute.
+                    See [SLA Coverage](/guides/instances/choosing/sla-coverage).
                 runtype:
                   type: string
                   description: |
@@ -162,6 +179,8 @@ paths:
                       description: Mount path for the volume inside the container (e.g., `/workspace`)
             example:
               image: vastai/base-image:@vastai-automatic-tag
+              disk: 50
+              target_reliability: 0.95
       responses:
         '200':
           description: Instance created successfully
@@ -179,7 +198,8 @@ paths:
                     description: ID of the newly created instance contract
                     example: 1234568
         '400':
-          description: Bad Request
+          description: |
+            Bad Request. Out-of-range `target_reliability` (below 0 or at least 1) is `invalid_args`. `invalid_sla_params` covers no SLA on the offer, a target above the host commitment, or an SLA fee above 1× compute. Also SSH key requirements. A missing offer is HTTP 400 `invalid_args` with `no_such_ask` (`msg` contains `error 404/3603`). A host account renting someone else's offer is also HTTP 400 `invalid_args` (`msg` contains `error 403/3586`). The HTTP status is 400 in both cases.
           content:
             application/json:
               schema:
@@ -192,6 +212,7 @@ paths:
                     type: string
                     enum:
                     - invalid_args
+                    - invalid_sla_params
                     - invalid_price
                     - no_ssh_key_for_vm
                   msg:
@@ -207,7 +228,8 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '403':
-          description: Forbidden
+          description: |
+            Forbidden. SLA is not enabled (`error` is `sla_disabled`). This is a platform-wide switch, not an account or region setting. A host account renting another host's offer is not 403; that is HTTP 400 with `error 403/3586` inside `msg`.
           content:
             application/json:
               schema:
@@ -218,32 +240,15 @@ paths:
                     example: false
                   error:
                     type: string
-                    example: invalid_args
+                    example: sla_disabled
                   msg:
                     type: string
-                    example: "error 403/3586: Offer 1234567 is not your own. Hosts can only rent their own machines."
+                    example: "SLA is not enabled."
                   ask_id:
                     type: integer
                     example: 1234567
         '404':
-          description: Offer not found or not available
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                    example: false
-                  error:
-                    type: string
-                    example: invalid_args
-                  msg:
-                    type: string
-                    example: "error 404/3603: no_such_ask Instance type by id 1234567 is not available."
-                  ask_id:
-                    type: integer
-                    example: 1234567
+          description: The offer was taken while the request was in progress. `error` is `no_such_ask` and `msg` contains `error 404/3659`. Re-search and do not retry the same offer ID.
         '410':
           description: Offer no longer available (when cancel_unavail is true and instance cannot start)
           content:
@@ -264,15 +269,12 @@ paths:
                     type: integer
                     example: 1234567
         '429':
-          description: Too Many Requests
+          description: Too Many Requests. Body follows the Accept header (usually HTML, not the JSON error shape). Retry-After and X-RateLimit-* headers are set.
           content:
-            application/json:
+            text/html:
               schema:
-                type: object
-                properties:
-                  detail:
-                    type: string
-                    example: API requests too frequent endpoint threshold=4.5
+                type: string
+                example: "API requests too frequent: endpoint threshold=4.5*1"
 components:
   securitySchemes:
     ApiKeyAuth:
@@ -293,9 +295,8 @@ components:
           type: string
 x-rate-limit:
   threshold: 4.5
-  penalty: 12
   per: request
-  description: Maximum request frequency per IP address for this endpoint
+  description: Rate limit per account for a signed-in API key. Unauthenticated calls are limited per IP address.
 x-input-validation:
   image:
     max_length: 1024
@@ -323,6 +324,6 @@ x-cli-commands:
   endpoint: /api/v0/asks/{id}/
   method: PUT
   examples:
-  - vast create instance 1234567 --image tensorflow/tensorflow:latest-gpu --disk 32
-  - vast create instance 1234567 --template abc123def456
-  - vast create instance 1234567 --price 0.4 --disk 100 --env JUPYTER_TOKEN=abc123
+  - vastai create instance 1234567 --image tensorflow/tensorflow:latest-gpu --disk 32
+  - vastai create instance 1234567 --template_hash abc123def456
+  - vastai create instance 1234567 --bid_price 0.4 --disk 100 --env JUPYTER_TOKEN=abc123