> For AI agents: the documentation index is at https://docs.gethandup.dev/llms.txt. Append .md to any page URL (without the trailing slash) for Markdown, for example https://docs.gethandup.dev/cli.md.

# pair_create

`POST /v1/pair`

Local only (unix socket or loopback bearer). Issues a one-time pairing code for `handup pair`. With `relay: true`, opens a fresh relay channel and returns a relay pairing link that carries the channel, the device's relay credential, the daemon's Noise public key, and the code.

## Request Body required

Media type: `application/json`

`object`

Local-only: create a pairing request (body for `POST /v1/pair`).

- **scope**: `string | null`

  Defaults to `decide`.

  Allowed values: `view` `decide` `submit`

- **name**: `string | null`

  Device name; the pairing page may suggest one when empty.

- **relay**: `boolean`

  Pair through the end-to-end encrypted relay (`remote.relay.url`)
  instead of the remote listener.

## Responses

### 200

Media type: `application/json`

`object`

- **code** (required): `string`

  One-time code (single use, expires after 2 minutes).

- **url** (required): `string`

  Pairing page URL; the code travels in the fragment so it never reaches server logs.

- **expires_at** (required): `integer` format: int64, >= 0

  Epoch milliseconds.

- **scope** (required): `string`

  Allowed values: `view` `decide` `submit`

- **name**: `string | null`
- **fingerprint**: `string | null`

  TLS leaf certificate SHA-256 fingerprint when the remote listener uses TLS.

- **mode** (required): `string`

### 409

Remote access (or the relay) is off or has no reachable base URL

### 502

The relay refused or could not be reached
