Catalogs and quotes

A template describes a workload and its runtime requirements. An offer describes a particular machine’s current rental terms. A quote snapshots their combination for one account and a limited time.

Resolve the template first

Read GET /api/v1/templates or GET /api/v1/templates/{idOrSlug} on https://amplerun-api.spiry.org. Template detail accepts either its UUID or slug. Keep these identifiers distinct:

• id: database UUID. Use this as template_id in offer searches and quote requests.
• template_id: human-readable identifier from the template specification. Do not put this slug into a UUID-only request field.

Published means available in the catalog. Compatibility labels describe built runtimes; they are not a claim that every hardware combination has been tested.

Find a compatible offer

Call GET /api/v1/offers?template_id=<template.id>. Inspect fit.fits and its reason. Compare memory, GPU count, runtime, region, hourly price for the whole machine, and availability class. Follow the returned next_cursor rather than assuming the first page is the whole market.

An offer can disappear between discovery and reservation. Do not invent fallback hardware or silently select a more expensive machine when a request fails.

Read the quote

Authenticated renters create a quote with POST /api/v1/quotes:

{
  "offer_id": "<offer UUID>",
  "template_id": "<template.id UUID>",
  "duration_limit_s": 300,
  "budget_micro": "1000000",
  "asset": "USDC"
}

Replace the placeholder IDs with returned values; this is a request shape, not a runnable reservation. Review expires_at, machine_rate_micro_per_hour, estimated_total_micro, budget_micro, platform_fee_bps, included disk and egress, and interruption terms. Quotes currently expire after 60 seconds. The response’s expires_at is authoritative.

Quotes are a retry exception

Creating a quote is free and does not hold funds or a machine. Each call creates a fresh quote, even if you reuse an Idempotency-Key. Reservation and stop requests have their own retry rules; see lifecycle.

For custom images, availability and host opt-in are feature-gated. Do not infer arbitrary-image support from the presence of an image field in a schema. Prefer a published compatible template for a first rental.