---
title: "Open a host pairing (installer; unauthenticated)"
method: POST
path: "/api/v1/hosts/pairings"
tags: ["hosts"]
---

# Open a host pairing (installer; unauthenticated)

`POST /api/v1/hosts/pairings`

## Request

- Base URL: `https://amplerun-api.spiry.org`
- URL: `https://amplerun-api.spiry.org/api/v1/hosts/pairings`
- Auth: none required

Called by the one-line installer (`curl -fsSL https://amplerun.com/host | sudo bash`). Returns a short user_code for a person to approve on /pair and a poll_secret only the installer holds; only their hashes are stored. Expires after 10 minutes. The code alone never yields a token. Rate-limited per source address.

## Request body

- object
  - `summary` object, required: What the installer reports about the machine. Unverified; shown to the approver.
    - `hostname` string, required
    - `os` string
    - `gpus` object[], required
      - `name` string, required
      - `vram_mib` integer

## Response `201`

Pairing opened.

- object
  - `pairing_id` string, uuid, required
  - `user_code` string, required: XXXX-XXXX from an alphabet without look-alike characters
  - `poll_secret` string, required: Shown once; needed to poll.
  - `expires_at` string, date-time, required
  - `interval` integer, required: Seconds between polls.
  - `verification_uri` string, required
  - `verification_uri_complete` string, required

## Other responses

- `default`: 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.

---

[API](https://skmtc.dev/amplerun/apis/amplerun-business-api.md) · [All operations](https://skmtc.dev/amplerun/apis/amplerun-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/amplerun/apis/amplerun-business-api/revisions/40944687fa52?raw)