Host 2752 sla api documentation

api-reference/openapi/yaml/create_instance.yaml

@@ -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:
@@ -61,8 +63,21 @@ paths:
                 disk:
                   type: number
                   format: float
+                  minimum: 8
+                  description: |
+                    Size of local disk partition (in GB). Minimum 8 when specified.
+                target_reliability:
+                  type: number
+                  format: float
+                  minimum: 0
+                  exclusiveMaximum: true
                   description: |
-                    Size of local disk partition (in GB)
+                    Client SLA coverage target (greater than 0 and less than 1). When set on an SLA-enabled offer
+                    (`sla_r_claim > 0`), locks SLA terms on the new contract. Omit or set to 0 for a non-SLA rental.
+                    Use the same value you used in search when comparing `dph_total`.
+                    Common failures: `invalid_args` when the offer has no SLA or the target is out of range;
+                    `invalid_price` when the quote is stale relative to search (re-search with matching storage
+                    and `target_reliability`, then rent again). See [SLA Coverage](/guides/instances/choosing/sla-coverage).
                 runtype:
                   type: string
                   description: |
@@ -162,6 +177,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 +196,10 @@ paths:
                     description: ID of the newly created instance contract
                     example: 1234568
         '400':
-          description: Bad Request
+          description: |
+            Bad Request. Includes invalid or out-of-range `target_reliability`, renting with SLA on a non-SLA
+            offer, SSH key requirements, and `invalid_price` when the create request does not match a fresh
+            search quote (re-search with the same `target_reliability` and disk/storage, then retry).
           content:
             application/json:
               schema:
@@ -323,6 +343,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 abc123def456
+  - vastai create instance 1234567 --price 0.4 --disk 100 --env JUPYTER_TOKEN=abc123

api-reference/openapi/yaml/list_machine.yaml

@@ -12,9 +12,11 @@ paths:
       summary: list machine
       description: |
         Creates or updates ask contracts for a machine to list it for rent on the vast.ai platform.
-        Allows setting pricing, minimum GPU requirements, end date and discount rates.
+        Allows setting offer pricing, rental types, end dates, discount rates, and SLA parameters.
 
-        CLI Usage: `vastai list machine <machine_id> [options]`
+        SLA request-body fields (`sla_r_claim`, `sla_sigma_x`, optional `sla_max_beta`) are supported on this REST endpoint. SLA activates when `sla_r_claim > 0`. Host-sent `sla_r_target` / legacy `sla_reliability` are ignored — clients choose coverage at search/rent time. The published CLI and SDK do not yet expose SLA fields — use the host console (**Set Pricing → SLA**) or REST/`curl` until CLI/SDK support ships.
+
+        CLI Usage (non-SLA fields): `vastai list machine <machine_id> [options]`
       security:
       - BearerAuth: []
       requestBody:
@@ -61,6 +63,39 @@ paths:
                   type: number
                   format: float
                   description: Maximum discount rate allowed for prepaid credits
+                sla_r_claim:
+                  type: number
+                  format: float
+                  minimum: 0
+                  maximum: 0.9999
+                  description: |
+                    Host reliability claim. Values above 0 enable SLA on the offer.
+                    Must be greater than 0 and at most 0.9999 when enabling SLA; exactly 1.0 is rejected.
+                    Set to 0 to disable SLA on new rentals.
+                sla_sigma_x:
+                  type: number
+                  format: float
+                  description: |
+                    Host confidence spread — how wide your belief is around the claim.
+                    Must be greater than 0 and at most 3.0. Defaults to 0.5 when enabling SLA.
+                sla_max_beta:
+                  type: number
+                  format: float
+                  description: |
+                    Optional ask term capping how aggressively long-running contracts may weight recent
+                    uptime versus longer history in settlement. Hosts do not set β — the platform derives
+                    β from the client's target_reliability at rent. Leave unset for uncapped. When set,
+                    must be in (0, 1) and at least the default beta derived at your claim.
+                sla_r_target:
+                  type: number
+                  format: float
+                  description: |
+                    Ignored on asks. Client coverage target is supplied at search/rent time
+                    (`target_reliability`), not set by the host.
+                sla_reliability:
+                  type: number
+                  format: float
+                  description: Legacy alias for sla_r_target; ignored on asks.
       responses:
         '200':
           description: Successful response
@@ -71,15 +106,43 @@ paths:
                 properties:
                   success:
                     type: boolean
-                  extended:
-                    type: integer
-                    description: Number of client contracts extended to new end date
-                  msg:
-                    type: string
-                    description: Status message if success is false
+                  you_sent:
+                    type: object
+                    description: Echo of the request body
+                  results:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        machine_id:
+                          type: integer
+                        user_id:
+                          type: integer
+                        extended:
+                          type: integer
+                          description: Number of rental contracts extended
+                        new_contracts:
+                          type: array
+                          items:
+                            type: integer
+                          description: IDs of newly created contracts
+                        upd_contracts:
+                          type: array
+                          items:
+                            type: integer
+                          description: IDs of updated contracts
                 example:
                   success: true
-                  extended: 2
+                  you_sent:
+                    machine: 12345
+                    sla_r_claim: 0.99
+                    sla_sigma_x: 0.5
+                  results:
+                  - machine_id: 12345
+                    user_id: 67890
+                    extended: 1
+                    new_contracts: []
+                    upd_contracts: [1]
         '400':
           description: Bad Request
           content:
@@ -89,23 +152,45 @@ paths:
                 properties:
                   error:
                     type: string
-                    example: invalid_args
+                    enum:
+                    - invalid_args
+                    - invalid_sla_params
+                    - sla_not_approved
+                    - sla_daemon_outdated
+                    example: invalid_sla_params
+                  msg:
+                    type: string
+                    example: No such machine(s) for your account
+        '401':
+          description: Unauthorized — missing permission or invalid API key
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: false
+                  error:
+                    type: string
                   msg:
                     type: string
-                    example: Invalid machine id or parameters
+                    example: Your key lacks the machine_write permission group
         '403':
-          description: Forbidden
+          description: Forbidden — machine locked
           content:
             application/json:
               schema:
                 type: object
                 properties:
                   error:
                     type: string
-                    example: not_authorized
+                    enum:
+                    - machine_locked
+                    example: machine_locked
                   msg:
                     type: string
-                    example: Only machine owner can create ask contracts
+                    example: Machine is decommissioned or migration-locked
       tags:
       - Machines
 components:

api-reference/openapi/yaml/schedule_maint.yaml

@@ -37,8 +37,11 @@ paths:
                 sdate:
                   type: string
                   format: date-time
-                  description: Start date and time of the maintenance window.
-                  example: '2023-10-30T14:00:00Z'
+                  description: |
+                    Start date and time of the maintenance window as an ISO 8601 UTC datetime
+                    (for example `2026-08-01T02:00:00Z`). The CLI `--sdate` flag accepts Unix epoch seconds
+                    and converts them to this format before calling the API.
+                  example: '2026-08-01T02:00:00Z'
                 duration:
                   type: integer
                   description: Duration of the maintenance window in hours.
@@ -128,5 +131,5 @@ x-cli-commands:
   description: Schedule maintenance for a machine.
   endpoint: /api/v0/machines/{machine_id}/dnotify
   method: PUT
-  example: vast-ai schedule maint 12345 --sdate "2023-10-30T14:00:00Z" --duration
-    2
+  example: vastai schedule maint 12345 --sdate 1698674400 --duration 2
+    --maintenance_category software

api-reference/openapi/yaml/search_offers.yaml

@@ -88,7 +88,25 @@ paths:
                       example: ["RTX_3090", "RTX_4090"]
                 reliability:
                   type: object
-                  description: 'Machine reliability score (0-1). Example: {"gte": 0.99}'
+                  description: 'Historical machine reliability score (0-1), not the host SLA claim. Example: {"gte": 0.99}'
+                target_reliability:
+                  type: object
+                  description: |
+                    Client SLA coverage target. Value must be greater than 0 and less than 1 (exclusive bounds —
+                    same as create-instance). When set, search prices include the SLA charge in dph_total and
+                    returns search.slaPremiumPerHour. Pass the same target again on PUT /api/v0/asks/{id}/ to
+                    enable coverage. Example: {"eq": 0.95}
+                has_sla:
+                  type: object
+                  description: |
+                    Restrict to offers with SLA enabled (true) or without (false). Example: {"eq": true}
+                  properties:
+                    eq:
+                      type: boolean
+                expected_reliability:
+                  type: object
+                  description: |
+                    Host SLA claim on the offer (0-1). Example: {"gte": 0.99}
                 num_gpus:
                   type: object
                   description: 'Number of GPUs. Example: {"gte": 4} or {"in": [1, 2, 4, 8]}'
@@ -266,7 +284,7 @@ paths:
                       Default is 8GB.
             example:
               limit: 100
-              type: on-demand
+              type: ondemand
               verified: 
                 eq: true
               rentable: 
@@ -362,7 +380,7 @@ paths:
                   vram_costperhour: 0.009876
                   webpage: null
                   vms_enabled: false
-                  expected_reliability: 0.5
+                  expected_reliability: 0.99
                   is_vm_deverified: false
                   resource_type: "gpu"
                   cluster_id: null
@@ -381,12 +399,14 @@ paths:
                   search:
                     gpuCostPerHour: 0.123456
                     diskHour: 0.123456
+                    slaPremiumPerHour: 0.008
                     totalHour: 0.234567
                     discountTotalHour: 0.01
                     discountedTotalPerHour: 0.224567
                   instance:
                     gpuCostPerHour: 0.01
                     diskHour: 0.02
+                    slaPremiumPerHour: 0.008
                     totalHour: 0.03
                     discountTotalHour: 0.001
                     discountedTotalPerHour: 0.029

api-reference/openapi/yaml/show_earnings.yaml

@@ -14,6 +14,8 @@ paths:
       description: |
         Retrieves the earnings history for a specified time range and optionally per machine.
 
+        **Note:** `per_day[]` aggregates SLA earnings across your entire fleet for each UTC day, even when `machid` is set. For machine-scoped SLA totals, use `per_machine[].sla_earn`.
+
         CLI Usage: `vastai show earnings [options]`
       security:
       - BearerAuth: []
@@ -28,12 +30,16 @@ paths:
         in: query
         schema:
           type: integer
-        description: Start day for the earnings report.
+        description: |
+          Start day for the earnings report as a UTC day index:
+          `floor(unix_epoch_seconds / 86400)`. Prefer `last_days` when you do not need an absolute window.
       - name: eday
         in: query
         schema:
           type: integer
-        description: End day for the earnings report.
+        description: |
+          End day for the earnings report as a UTC day index:
+          `floor(unix_epoch_seconds / 86400)` (inclusive end of the window when used with `sday`).
       - name: machid
         in: query
         schema:
@@ -63,6 +69,9 @@ paths:
                         type: number
                       total_bwd:
                         type: number
+                      total_sla:
+                        type: number
+                        description: Net SLA earnings over the requested window.
                   username:
                     type: string
                   email:
@@ -107,6 +116,9 @@ paths:
                           type: number
                         bwd_earn:
                           type: number
+                        sla_earn:
+                          type: number
+                          description: Net SLA earnings for this machine over the window.
                   per_day:
                     type: array
                     items:
@@ -122,6 +134,9 @@ paths:
                           type: number
                         bwd_earn:
                           type: number
+                        sla_earn:
+                          type: number
+                          description: Net host SLA settlement for the UTC day. Positive when the host keeps the SLA charge; negative when the host credits the client.
         '400':
           description: Bad Request - Invalid input syntax
           content: