Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Amplerun Com Catalog API
version: 3.0.0
description: 'Operations tagged catalog across 2 of this provider''s published API definitions: openapi.json, amplerun-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://amplerun-api.spiry.org
description: Production machine API (direct origin)
- url: https://amplerun.com
description: Production frontend-compatible API origin
tags:
- name: Catalog
description: Public templates and GPU offers. No credential needed.
paths:
/api/v1/offers:
get:
operationId: listOffers
tags:
- Catalog
summary: List admitted offers (public)
description: 'Listed offers on available, admitted machines with a heartbeat in the last 90 seconds; only these can be reserved. Server-side filters are model, gpu_count, max_rate_micro_per_hour, verification_level, continent and template_id; sort defaults to price_asc, and near puts one continent''s machines first. There is no VRAM, region, RAM, disk or bandwidth filter: each item carries vram_bytes, region, ram_bytes and disk_bytes when measured, for client-side filtering. With template_id (D-19(c)) every item carries a server-computed fit object. No cached public responses.'
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: template_id
in: query
required: false
schema:
$ref: '#/components/schemas/UUID'
description: Compute per-offer fit against this template's vram_fit (D-19(c)). The template's `id` (UUID), not its slug; resolve a slug with GET /api/v1/templates/{templateId}. Unknown or unpublished template -> 404, a slug -> 422.
- name: fits_for
in: query
required: false
schema:
enum:
- all
description: Additive. `all` adds fits_template_ids to every item, the ids of every published template that fits that offer under the same rule as template_id, in one read. Any other value -> 422.
- name: sort
in: query
required: false
schema:
enum:
- price_asc
- price_desc
- vram_desc
- reliability_desc
- uptime_desc
- newest
- verification
- net_desc
- tflops_desc
- ai_speed_desc
default: price_asc
description: Keyset sort order; an unknown value falls back to price_asc.
- name: verification_level
in: query
required: false
schema:
enum:
- unverified
- auto_verified
- manually_verified
description: Only machines at exactly this verification level.
- name: include_unverified
in: query
required: false
schema:
type: boolean
default: false
description: Also list machines that have not passed admission yet.
- name: min_bandwidth_mbps
in: query
required: false
schema:
type: integer
minimum: 0
description: netfacts lane. Only machines whose MEASURED download rate is at least this; machines that never measured are excluded (they cannot claim a rate).
- name: max_rate_micro_per_hour
in: query
required: false
schema:
$ref: '#/components/schemas/MicroAmount'
description: Only offers whose total machine rate is at or below this amount.
- name: gpu_count
in: query
required: false
schema:
type: integer
minimum: 1
description: Only offers whose machine manifest lists at least this many devices.
- name: model
in: query
required: false
schema:
type: string
minLength: 1
description: Case-insensitive substring match on the first device model in the manifest.
- name: tier
in: query
required: false
schema:
enum:
- container
- inference
description: Only machines of this tier (D-23).
- name: backend
in: query
required: false
schema:
enum:
- cuda
- rocm
- sycl
- vulkan
- metal
description: Only machines with a device serving this backend.
- name: continent
in: query
required: false
schema:
$ref: '#/components/schemas/ContinentFilter'
description: Only machines on this continent (americas = NA + SA). Machines with an unknown location are excluded. Any other value -> 422.
- name: near
in: query
required: false
schema:
$ref: '#/components/schemas/ContinentFilter'
description: Order this continent's machines first (lower latency), then by sort. Keeps every other machine. Any other value -> 422.
responses:
'200':
description: Page of offer summaries.
content:
application/json:
schema:
type: object
required:
- items
- next_cursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/OfferSummary'
next_cursor:
anyOf:
- type: string
- type: 'null'
default:
$ref: '#/components/responses/Error'
servers:
- url: https://amplerun-api.spiry.org
description: Production machine API (direct origin)
- url: https://amplerun.com
description: Production frontend-compatible API origin
/api/v1/offers/{id}:
get:
operationId: getOffer
tags:
- Catalog
summary: Get one offer (public)
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/UUID'
responses:
'200':
description: Offer summary.
content:
application/json:
schema:
$ref: '#/components/schemas/OfferSummary'
default:
$ref: '#/components/responses/Error'
servers:
- url: https://amplerun-api.spiry.org
description: Production machine API (direct origin)
- url: https://amplerun.com
description: Production frontend-compatible API origin
/api/v1/templates:
get:
operationId: listTemplates
tags:
- Catalog
summary: List published templates (public)
description: D-19(c). Cursor paged; filters kind and min_vram_bytes (templates whose vram_fit.min_vram_bytes <= the given value). Only published templates (bound to at least one admitted machine by a qualification record) are listed. No cached public responses.
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: kind
in: query
required: false
schema:
enum:
- model
- classical
- custom
- name: min_vram_bytes
in: query
required: false
schema:
$ref: '#/components/schemas/DecimalString'
description: Return templates that fit a device with this much VRAM.
- name: backend
in: query
required: false
schema:
enum:
- cuda
- rocm
- sycl
- vulkan
- metal
description: Only templates with a built runtime for this backend ("Works on").
responses:
'200':
description: Page of templates.
content:
application/json:
schema:
type: object
required:
- items
- next_cursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/Template'
next_cursor:
anyOf:
- type: string
- type: 'null'
default:
$ref: '#/components/responses/Error'
servers:
- url: https://amplerun-api.spiry.org
description: Production machine API (direct origin)
- url: https://amplerun.com
description: Production frontend-compatible API origin
/api/v1/templates/{templateId}:
get:
operationId: getTemplate
tags:
- Catalog
summary: Get one published template (public)
parameters:
- name: templateId
in: path
required: true
schema:
type: string
minLength: 1
description: Template UUID or its slug (spec.template_id, e.g. qwen3-8b-awq); unpublished -> 404.
responses:
'200':
description: Template.
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
default:
$ref: '#/components/responses/Error'
servers:
- url: https://amplerun-api.spiry.org
description: Production machine API (direct origin)
- url: https://amplerun.com
description: Production frontend-compatible API origin
components:
schemas:
OfferSummary:
type: object
additionalProperties: false
required:
- offer_id
- machine_id
- observed_at
- offer_version
- readiness
- total_rate_micro_per_hour
- included_quotas
- available_from
- available_until
- maintenance_windows
- expected_version
properties:
offer_id:
$ref: '#/components/schemas/UUID'
machine_id:
$ref: '#/components/schemas/UUID'
observed_at:
$ref: '#/components/schemas/Rfc3339Utc'
offer_version:
$ref: '#/components/schemas/DecimalString'
expected_version:
$ref: '#/components/schemas/DecimalString'
readiness:
enum:
- ready
- provisioning
- unavailable
total_rate_micro_per_hour:
$ref: '#/components/schemas/MicroAmount'
included_quotas:
type: object
additionalProperties: false
required:
- included_disk_gib
- included_egress_gib
properties:
included_disk_gib:
type: integer
minimum: 0
included_egress_gib:
type: integer
minimum: 0
available_from:
$ref: '#/components/schemas/Rfc3339Utc'
available_until:
$ref: '#/components/schemas/Rfc3339Utc'
maintenance_windows:
type: array
items:
type: object
additionalProperties: false
required:
- starts_at
- ends_at
- reason
properties:
starts_at:
$ref: '#/components/schemas/Rfc3339Utc'
ends_at:
$ref: '#/components/schemas/Rfc3339Utc'
reason:
type: string
gpu_count:
type: integer
minimum: 1
model:
type: string
vram_bytes:
$ref: '#/components/schemas/DecimalString'
region:
type: string
country:
type: string
pattern: ^[A-Z]{2}$
description: Additive. ISO 3166-1 alpha-2 country of the machine, read by the controller from the agent's request country as reported by the trusted proxy (never from host input). Absent when unknown.
continent:
$ref: '#/components/schemas/Continent'
ram_bytes:
$ref: '#/components/schemas/DecimalString'
disk_bytes:
$ref: '#/components/schemas/DecimalString'
measured_bandwidth_mbps:
type: integer
minimum: 0
description: netfacts lane. Measured DOWNLOAD rate in Mbps; additive. Absent = never measured (never 0).
net_up_mbps:
type: integer
minimum: 0
description: netfacts lane. Measured UPLOAD rate in Mbps; rides the same measurement as measured_bandwidth_mbps.
net_latency_ms:
type: integer
minimum: 0
description: netfacts lane. Median HTTPS latency in ms from the same measurement.
speedtest_at:
$ref: '#/components/schemas/Rfc3339Utc'
description: netfacts lane. When the current net facts were measured; renders 'measured N ago' honestly.
tflops_bf16:
type: number
exclusiveMinimum: 0
description: AI Speed. Measured dense BF16 matmul TFLOPS per GPU (the MIN across the machine's GPUs); additive. Absent = never measured (never 0).
tflops_total:
type: number
exclusiveMinimum: 0
description: AI Speed. tflops_bf16 x gpu_count, computed, one decimal. Absent with tflops_bf16 or gpu_count.
mem_bw_gbps:
type: number
exclusiveMinimum: 0
description: AI Speed. Measured device memory bandwidth in GB/s per GPU (the MIN across the machine's GPUs). Absent = never measured (never 0).
ai_speed:
type: integer
minimum: 1
description: AI Speed. round(100*sqrt((tflops_bf16/165.2)*(mem_bw_gbps/1008))); RTX 4090 = 100. Absent unless both figures were measured.
bench_at:
$ref: '#/components/schemas/Rfc3339Utc'
description: AI Speed. When the current figures were measured.
bench_flag:
type: string
enum:
- unverified_spec
description: AI Speed. The GPU has no datasheet row to check the figures against.
disk_free_bytes:
$ref: '#/components/schemas/DecimalString'
description: Additive. Free disk space in bytes from the machine's latest telemetry sample. Absent when there is no sample, the sample is older than 60 seconds (2x the 30 s heartbeat, the host console STALE_AFTER_S rule) or the agent did not report it; never 0 as a stand-in.
uptime_s:
$ref: '#/components/schemas/DecimalString'
description: Additive. Seconds since the machine booted, from the latest telemetry sample. Absent under the same rules as disk_free_bytes.
gpu_utilization_pct:
type: number
minimum: 0
maximum: 100
description: Additive. Live GPU load, the PEAK across the machine's devices, from the latest telemetry sample. Absent under the same rules as disk_free_bytes, and when no device reported utilisation. 0 means measured idle.
telemetry_at:
$ref: '#/components/schemas/Rfc3339Utc'
description: Additive. observed_at of the telemetry sample disk_free_bytes, uptime_s and gpu_utilization_pct came from. Present only with at least one of them; absent whenever they are.
template_compatibility:
type: array
items:
type: string
manifest_hash:
$ref: '#/components/schemas/Sha256Hash'
fit:
$ref: '#/components/schemas/TemplateFit'
description: D-19(c). Present only when the request carried template_id; computed server-side from the template vram_fit against measured device VRAM.
fits_template_ids:
type: array
items:
$ref: '#/components/schemas/UUID'
description: Additive. Present only when the request carried fits_for=all; the ids of every published template that fits this offer (the same rule as fit).
platform_fee_bps:
type: integer
minimum: 0
description: Additive. Platform fee frozen into this offer version, in basis points (500 = 5%), taken out of each charge.
verification_level:
enum:
- unverified
- auto_verified
- manually_verified
description: Additive. How the machine's hardware claims were verified.
admitted:
type: boolean
description: 'Additive. Whether the machine has passed admission (a passed qualification for its current manifest). false is an unverified listing: shown in the catalog, never quoted or reserved (409 CONFLICT).'
tier:
enum:
- container
- inference
description: 'Additive (D-23). container: SSH containers under the launch profile. inference: managed models on a signed, hash-pinned runtime with no renter code, reached over the host''s outbound session (community inference: don''t send sensitive data).'
backends:
description: Additive. Backends the machine's devices serve, in preference order (cuda > rocm > sycl > vulkan > metal). A template runs here with the first one it has a runtime for.
type: array
items:
enum:
- cuda
- rocm
- sycl
- vulkan
- metal
reliability:
description: Additive. Approximate reliability score from machine fields only (no per-job joins on the catalog path).
type: object
additionalProperties: false
required:
- score
- stars
- band
- approximate
properties:
score:
type: number
minimum: 0
maximum: 100
stars:
type: string
band:
type: string
approximate:
type: boolean
availability_class:
$ref: '#/components/schemas/AvailabilityClass'
preemption_notice_s:
anyOf:
- type: integer
minimum: 0
maximum: 3600
- type: 'null'
description: D-22. Notice in seconds (SIGTERM plus /work/.amplerun-preempt) before the host stops an interruptible rental; null for dedicated.
interruption_estimate:
description: D-22. Present for interruptible offers (horizon 4 h in the catalog); null for dedicated.
anyOf:
- $ref: '#/components/schemas/InterruptionEstimate'
- type: 'null'
description: No host management address is ever exposed. gpu_count, model and vram_bytes come from the machine manifest; vram_bytes is per GPU and is absent when the GPUs differ or memory was not measured. region, ram_bytes and disk_bytes are absent when the host did not measure them, never 0.
example:
offer_id: 8b0c2f4e-1d3a-4c5b-9e6f-7a8b9c0d1e2f
machine_id: 5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f
observed_at: '2026-09-25T12:00:00Z'
offer_version: '3'
expected_version: '12'
readiness: ready
total_rate_micro_per_hour: '450000'
platform_fee_bps: 500
included_quotas:
included_disk_gib: 100
included_egress_gib: 50
available_from: '2026-09-25T00:00:00Z'
available_until: '2026-10-25T00:00:00Z'
maintenance_windows: []
gpu_count: 1
model: NVIDIA GeForce RTX 4090
vram_bytes: '25757220864'
region: us-east-1
manifest_hash: sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
verification_level: auto_verified
admitted: true
fit:
fits: true
reason: ok
InterruptionEstimate:
type: object
additionalProperties: false
required:
- runs
- uninterrupted
- horizon_h
- computed_at
- summary
description: 'D-22, interruptible offers only. Plain observed counts, never a prediction. A run is one continuous period in which the host reported the machine offerable (from heartbeats); it counts when it ended, or has already lasted horizon_h. uninterrupted is null below the sample gate (20 runs): not enough history.'
properties:
runs:
type: integer
minimum: 0
description: Most recent decided runs counted (at most 40).
uninterrupted:
anyOf:
- type: integer
minimum: 0
- type: 'null'
description: Of those runs, how many lasted horizon_h without interruption; null below the sample gate.
horizon_h:
type: integer
minimum: 1
computed_at:
$ref: '#/components/schemas/Rfc3339Utc'
summary:
type: string
description: The counts in words, e.g. "34 of the last 40 runs lasted 4 h without interruption" or "Not enough history (12 runs so far)".
Sha256Hash:
type: string
pattern: ^sha256:[0-9a-f]{64}$
example: sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
UUID:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
example: 3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40
DecimalString:
type: string
pattern: ^(0|[1-9][0-9]*)$
description: Unsigned base-10 integer as string; never a float.
example: '1'
ImageDigest:
type: string
pattern: ^[^@\s]+@sha256:[0-9a-f]{64}$
example: registry.amplerun.com/templates/pytorch-cuda@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
AvailabilityClass:
type: string
enum:
- dedicated
- interruptible
description: 'D-22. dedicated (the default) is never preempted. interruptible is sold only from idle or co-listed hosts: the host may take the machine back after preemption_notice_s seconds of notice, and billing stops at the notice.'
TemplateRuntime:
type: object
additionalProperties: false
required:
- tier
- image_digest
properties:
tier:
enum:
- container
- inference
image_digest:
$ref: '#/components/schemas/ImageDigest'
Continent:
description: 'Additive. Continent derived from country: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America. Absent when the country is unknown.'
enum:
- AF
- AN
- AS
- EU
- NA
- OC
- SA
Template:
description: Public template (D-19(b)); mirrors packages/contracts/schemas/template.schema.json, which remains the authority for templates.spec. kind=model requires model_ref and readiness.
type: object
additionalProperties: false
required:
- id
- published
- template_id
- name
- template_version
- image_digest
- launch_profile_version
- kind
- engine
- vram_fit
- exposes
- env
- min_gpu_count
- required_runtime
- setup_notes
properties:
id:
$ref: '#/components/schemas/UUID'
published:
type: boolean
template_id:
type: string
pattern: ^[a-z0-9][a-z0-9-]{0,63}$
name:
type: string
minLength: 1
template_version:
type: string
minLength: 1
image_digest:
$ref: '#/components/schemas/ImageDigest'
description: Pinned OCI reference (name@sha256:<64 hex>) — the same form quotes, START commands and qualification records carry.
launch_profile_version:
type: string
minLength: 1
kind:
enum:
- model
- classical
- custom
engine:
enum:
- vllm
- llamacpp
- comfyui
- faster-whisper
- pytorch
- jupyter
- ollama
- oci
model_ref:
type: object
additionalProperties: false
required:
- hf_repo
- revision
- files
properties:
hf_repo:
type: string
minLength: 1
revision:
type: string
minLength: 1
files:
type: array
minItems: 1
items:
type: object
additionalProperties: false
required:
- name
- sha256
- size_bytes
properties:
name:
type: string
pattern: ^(?!\.\.?$)[A-Za-z0-9._-]+$
sha256:
type: string
pattern: ^[0-9a-f]{64}$
size_bytes:
$ref: '#/components/schemas/DecimalString'
quantization:
type: string
minLength: 1
vram_fit:
type: object
additionalProperties: false
required:
- min_vram_bytes
- est_weights_bytes
- est_kv_bytes_per_1k_tokens
properties:
min_vram_bytes:
$ref: '#/components/schemas/DecimalString'
est_weights_bytes:
$ref: '#/components/schemas/DecimalString'
est_kv_bytes_per_1k_tokens:
$ref: '#/components/schemas/DecimalString'
readiness:
type: object
additionalProperties: false
required:
- http_path
- expect_status
properties:
http_path:
type: string
pattern: ^/
expect_status:
type: integer
minimum: 100
maximum: 599
exposes:
type: array
minItems: 1
items:
type: object
additionalProperties: false
required:
- name
- port
- protocol
properties:
name:
type: string
minLength: 1
port:
type: integer
minimum: 1
maximum: 65535
protocol:
enum:
- http
- ssh
- tcp
env:
type: object
propertyNames:
pattern: ^[A-Z][A-Z0-9_]{1,63}$
additionalProperties:
type: string
min_gpu_count:
type: integer
minimum: 1
required_runtime:
enum:
- cuda
- rocm-hip
- level-zero
- opencl
- xpu
setup_notes:
type: string
runtimes:
description: 'Additive. One template, many backends: the same weights and API contract per backend. tier container is an OCI image; tier inference is the signed Tier B runtime artifact (<source>@sha256:<hex>). The control plane picks the machine''s runtime by preference (cuda > rocm > sycl > vulkan > metal) and pins its digest in the quote and lease.'
type: object
additionalProperties: false
properties:
cuda:
$ref: '#/components/schemas/TemplateRuntime'
rocm:
$ref: '#/components/schemas/TemplateRuntime'
sycl:
$ref: '#/components/schemas/TemplateRuntime'
vulkan:
$ref: '#/components/schemas/TemplateRuntime'
metal:
$ref: '#/components/schemas/TemplateRuntime'
backends:
description: Additive. Backends with a built runtime, in preference order ("Works on" filter). Spec compatibility, not a hardware test.
type: array
items:
enum:
- cuda
- rocm
- sycl
- vulkan
- metal
works_on:
description: Additive. Hardware vendors those backends cover. Spec compatibility only; a hardware report is what says "tested on".
type: array
items:
enum:
- nvidia
- amd
- intel
- apple
ContinentFilter:
description: A continent code, case-insensitive, or americas (North and South America).
enum:
- af
- an
- as
- eu
- na
- oc
- sa
- americas
- AF
- AN
- AS
- EU
- NA
- OC
- SA
ErrorEnvelope:
type: object
additionalProperties: false
required:
- error
example:
error:
code: QUOTE_EXPIRED
message: quote expired
retryable: false
request_id: 3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40
properties:
error:
type: object
additionalProperties: false
required:
- code
- message
- retryable
- request_id
properties:
code:
type: string
minLength: 1
description: 'Stable machine-readable code (packages/contracts ERROR_CODES). Business routes use UNAUTHENTICATED (401), FORBIDDEN (403: missing scope, step-up or role), NOT_FOUND (404, also used where existence must not leak), INVALID_INPUT (422), ADMISSION_PAUSED and AUTHORIZATION_INVALID (403), IDEMPOTENCY_CONFLICT, CONFLICT, VERSION_CONFLICT, STALE_VERSION, STALE_FENCE, QUOTE_EXPIRED, INSUFFICIENT_FUNDS and STOP_IRREVERSIBLE (409), and UNAVAILABLE (503, or 429 when rate limited). The host-agent protocol adds BUDGET_VERSION_OLDER, BUDGET_FUNDING_MISMATCH, LEASE_SEQ_REPLAY, COMMAND_EXPIRED, UNSUPPORTED_PROTOCOL_VERSION and UNKNOWN_COMMAND_KIND. New codes may appear; handle an unknown code by its HTTP status.'
message:
type: string
minLength: 1
description: Human-readable; never contains secrets or stack traces.
retryable:
type: boolean
description: 'True when the identical request may succeed later: back off and retry with the same Idempotency-Key.'
request_id:
$ref: '#/components/schemas/UUID'
TemplateFit:
description: D-19(c) per-offer fit verdict for a template, computed server-side from vram_fit against measured device VRAM. reason is human-readable and non-empty when fits is false.
type: object
additionalProperties: false
required:
- fits
- reason
properties:
fits:
type: boolean
reason:
type: string
MicroAmount:
$ref: '#/components/schemas/DecimalString'
description: Money in micro-units of the settlement asset as a base-10 integer string ("5000000" is 5 USDC). Never a float.
example: '5000000'
Rfc3339Utc:
type: string
format: date-time
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z$
example: '2026-09-25T12:00:00Z'
responses:
Error:
description: Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
parameters:
Limit:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
Cursor:
name: cursor
in: query
required: false
schema:
type: string
description: Opaque pagination cursor from a previous response.
securitySchemes:
sessionAuth:
type: http
scheme: bearer
description: 'Bearer credential. Programs and agents send a scoped API key as `Authorization: Bearer ark_...` (renter and/or host scope; created once at https://amplerun.com/account#api-keys or POST /api/v1/account/api-keys; the secret is shown only at creation). The web app uses a pinned Better Auth session. API keys never reach /api/v1/admin/*. Step-up (recent re-auth) is required where noted.'
externalDocs:
description: Guides, SDKs, CLI and the MCP server for AI agents
url: https://amplerun.com/docs/api
x-refined-from:
- openapi.json
- amplerun-com-openapi.json