Host 2752 sla api documentation - #162
Open
robertfernandez-vast wants to merge 45 commits into
Open
Conversation
robertfernandez-vast
requested review from
agustin-vastai,
jsbcannell,
liam-at-vast,
michele-cloud and
stackanthony
July 7, 2026 04:30
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Register SLA pages in nav, align OpenAPI with listing/backtester endpoints, and fix clarity issues flagged across all-hosts review (confidence direction, broken links, jargon, onboarding gaps). Co-authored-by: Cursor <cursoragent@cursor.com>
Align create_asks error codes with production, add OpenAPI earnings fleet-scope note, choose-your-path routing, and merge duplicate FAQs. Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify economics sign convention, console LIST step, dph_total, OpenAPI SLA CLI caveat, fleet backtest error handling, and webhook subscription key. Co-authored-by: Cursor <cursoragent@cursor.com>
Document console Save-then-LIST vs REST publish, host-centric economics tables, earnings rate limits, merge semantics, and maintenance webhooks. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix API error shapes, UTC day-index docs, confidence/claim clarity, economics table wording, and host overview SLA publish steps. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix confidence preset percentages, console step numbering, economics tail-risk cap, fleet listing workflow, and backtester error table. Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify hourly vs daily premium framing, promote fleet listing section, fix setup URL consistency, and improve earnings API fleet guidance. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix show machines jq path for partial updates, define dph_total early, and correct backtester economics walkthrough link. Co-authored-by: Cursor <cursoragent@cursor.com>
Extend show-machines OpenAPI for SLA read path, add search field mapping, fix daily vs window monitoring examples, uptime measurement, and hosting fixes. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix SLA opt-in phrasing, fleet listing read-modify-write pattern, UTC monitoring dates, and confidence preset wording. Co-authored-by: Cursor <cursoragent@cursor.com>
Add claim headroom guidance, reframe confidence presets, fix search verification jq, and warn against copying backtester p into sla_sigma_x. Co-authored-by: Cursor <cursoragent@cursor.com>
Add console-first onboarding note, Save-vs-LIST update path, fix fleet listing O(n²) pattern, and clarify reboot SLA risk wording. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix sliced-machine search verification, clarify reliability filter vs expected_reliability, and align machine-scoped sla_earn guidance. Co-authored-by: Cursor <cursoragent@cursor.com>
…wording Hosts publish claim/confidence only; clients choose target at search. Replace insurance/premium language with SLA charge per HOST-2752 compliance notes. Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify SLA opt-in and on-demand scope for clients, align search/instances OpenAPI, and remove internal release notes from the publishable tree. Co-authored-by: Cursor <cursoragent@cursor.com>
Document search→rent SLA binding with REST examples, clarify console opt-in and maintenance CLI paths, and fix OpenAPI slaPremiumPerHour examples. Co-authored-by: Cursor <cursoragent@cursor.com>
Document create-instance target_reliability binding, align schedule-maint sdate formats, and harden search/rent API examples. Co-authored-by: Cursor <cursoragent@cursor.com>
Align schedule-maint category and framing with the API enum; clarify console SLA filter and outage billing. Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify CLI create-instance lacks target_reliability; document REST-only maintenance_reason and raise maintenance tooling prerequisite. Co-authored-by: Cursor <cursoragent@cursor.com>
Harden search→rent SLA handoff, schedule-maint examples, earnings day indices, and create-instance error guidance. Co-authored-by: Cursor <cursoragent@cursor.com>
Strip CMS frontmatter, align storage/beta/OpenAPI notes, and fix create-instance error codes for integrators. Co-authored-by: Cursor <cursoragent@cursor.com>
Document SLA create-instance error modes in OpenAPI and un-nest client Choose your path from the opt-in Note. Co-authored-by: Cursor <cursoragent@cursor.com>
Rewrite sla_max_beta as an optional client-β cap and use an absolute FAQ href for Mintlify. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix stale end_date examples, elevate CLI search-vs-rent SLA warnings, and soften sla_max_beta wording. Co-authored-by: Cursor <cursoragent@cursor.com>
Repair search-offers examples fence, split backtester 400 error rows, and name show-instances verify path. Co-authored-by: Cursor <cursoragent@cursor.com>
Resolve CLI verify contradiction, document instances pagination and search order/limit for SLA automation. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Fix maint scheduling examples, dph_total/bandwidth wording, after_token pagination, and CLI rent decision rule. Co-authored-by: Cursor <cursoragent@cursor.com>
Align create-instance 410/storage notes and correct SDK volume/duration tooling scope. Co-authored-by: Cursor <cursoragent@cursor.com>
Correct search offer id labeling, console disk sizing path, and REST search parity filters. Co-authored-by: Cursor <cursoragent@cursor.com>
Align outage billing wording, confidence vs credit risk, and search target_reliability bounds. Co-authored-by: Cursor <cursoragent@cursor.com>
Harden fleet listing example, add cancel/reschedule maintenance, and clarify daemon preflight. Co-authored-by: Cursor <cursoragent@cursor.com>
Stop fleet script from inventing SLA claims; document maint rate limits; trim duplicate tooling warnings. Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify cross-channel storage defaults and mark create-instance SLA as REST-only in OpenAPI. Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify GiB/GB search→rent integers, console-only SLA credits, and create-instance SLA gaps. Co-authored-by: Cursor <cursoragent@cursor.com>
Fix backtester confidence wording, create-instance offer-id labeling, and OpenAPI disk/lookback notes. Co-authored-by: Cursor <cursoragent@cursor.com>
Surface client billing reconciliation limits early and align create-instance CLI examples with shipped vastai. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Clarify self-test billing, add host checklist and SLA key recipe, and fix offer-id / date platform notes. Co-authored-by: Cursor <cursoragent@cursor.com>
Wrap host SLA scoped-key JSON in required api object and fix create-instance example fences. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Align instances pagination defaults, document SLA search CLI warnings, and relocate client key recipe. Co-authored-by: Cursor <cursoragent@cursor.com>
robertfernandez-vast
force-pushed
the
HOST-2752-SLA-API-Documentation
branch
from
July 28, 2026 15:57
ab838e7 to
73c1583
Compare
Regenerate openapi.yaml so nullable types and unique operationIds match the yaml sources and pass verify-openapi / mint openapi-check. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
HOST-2752: Host SLA API documentation
Branch:
HOST-2752-SLA-API-DocumentationBase:
origin/main(merge-base112323ba)Scope: Changes on the subject branch relative to
origin/main(git diff origin/main...HEAD).Summary
This branch adds host-facing documentation for SLA (Service Level Agreement) offers on Vast.ai: how hosts enable uptime guarantees, set pricing parameters, preview economics, list via console or REST, and monitor settlements. It introduces two new guide pages (
host/sla-offers,host/sla-backtester), extends OpenAPI for listing, backtesting, and earnings monitoring, and updates CLI/SDK snippets to state honestly that SLA flags are REST/console-only today.The work went through 12 iterative doc-review fix cycles after the initial draft. Latest multi-persona review reported no critical issues; remaining feedback is polish and edge-case clarity (sliced-machine search verification, client-facing SLA guide as a future follow-up).
Audience: Hosts (console-first and API automation). Risk: Documentation-only — no application code changes. Hosts should treat CLI/SDK SLA parameters as unavailable until tooling ships.
Details
Host guides (new)
/host/sla-offerscreate_asks, fleet listing, monitoring, common errors/host/sla-backtesterGET /api/v0/host/sla_backtest/— historical replay,worst_day_loss, fleet workflow, error responsesKey themes documented on SLA Offers:
PUT /api/v0/machines/create_asks/publishes in one request.sla_r_target,sla_r_claim,sla_sigma_x(and legacysla_reliability); validation bounds andinvalid_sla_params.dph_total, daily UTC settlement, asymmetric payout risk (worst_day_loss).GET /api/v0/users/{user_id}/machine-earnings/— useper_machine[].sla_earn; avoid fleet-wideper_day[].sla_earnfor single-machine checks.OpenAPI and API reference
PUT /api/v0/machines/create_asks/— SLA request fields,invalid_sla_params, 401 permission shape, 403machine_lockedGET /api/v0/host/sla_backtest/spec (sla_backtest.yaml)sla_earnonper_machine[]andper_day[]; fleet-scope note whenmachidis set--rawoutput for read-modify-write partial updatesmachine_readSynced monolithic
api-reference/openapi.yamlwith YAML sources underapi-reference/openapi/yaml/.Snippets and cross-links
snippets/host/cli/list-machine.mdxandsnippets/host/sdk/list-machine.mdx: SLA parameters marked not yet available in published CLI/SDK; point to console or REST.host/hosting-overview.mdx: SLA bullet, maintenance + SLA section, search/setup URL fixes, storageGBwording, FAQ grammar.docs.json: Nav entries forhost/sla-offersandhost/sla-backtester.API endpoints documented (REST)
PUT/api/v0/machines/create_asks/machine,sla_r_target,sla_r_claim,sla_sigma_x)GET/api/v0/host/sla_backtest/machine_id,r,p, optional date range)GET/api/v0/users/{user_id}/machine-earnings/machid,last_days,per_machine[].sla_earn)GET/api/v0/machines/show machines --raw)Files / areas touched
host/sla-offers.mdx(new),host/sla-backtester.mdx(new),host/hosting-overview.mdxopenapi.yaml,list_machine.yaml,sla_backtest.yaml,show_earnings.yaml,show_machines.yamlsnippets/host/cli/list-machine.mdx,snippets/host/sdk/list-machine.mdxdocs.json,api-reference/permissions.mdxTotal: 12 files, ~1,700 insertions, ~80 deletions.
Upgrade / rollout
create_asks/until CLI/SDK SLA support is released. API keys needmachine_write(listing),machine_read(backtester),billing_read(earnings).Commits
Newest first (
origin/main..HOST-2752-SLA-API-Documentation):302c873— docs(sla): address doc-review consensus (cycle 12)a6f228a— docs(sla): address doc-review consensus (cycle 11)150d8b7— docs(sla): address doc-review consensus (cycle 10)89be3c4— docs(sla): address doc-review consensus (cycle 9)db4003d— docs(sla): address doc-review consensus (cycle 8)b3ce882— docs(sla): address doc-review consensus (cycle 7)5f8d63a— docs(sla): address doc-review consensus (cycle 6)40ce178— docs(sla): address doc-review consensus (cycle 5)603e773— docs(sla): address doc-review consensus (cycle 4)cbfe3f5— docs(sla): address doc-review consensus (cycle 3)09f8084— docs(sla): address doc-review consensus (cycle 2)5078cdc— docs(sla): address doc-review consensus (cycle 1)50b9465— Address doc-review feedback for host SLA documentation.d66ac30— First draft for SLA documentation