Make a pairing code

POST

/pair/start

const url = 'http://127.0.0.1:7700/api/pair/start';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"owner":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://127.0.0.1:7700/api/pair/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "owner": true }'

Owner only. A one-time code for the QR code on the box’s own screen. It works once and expires after 5 minutes. With owner: true, the phone that redeems it becomes an owner device; the flag is ignored from anyone who is not already the owner. url opens the GurtOS web app (BOX_APP) with the code. boxUrl is the box’s own pairing page, and is there only when BOX_URL or remote access gives the box an address. With remote access off, the portal’s QR code opens boxUrl on the home network. POST /pair/new is the same route under its older name.

Authorizations

deviceToken
accessToken

Request Body

application/json

object

owner

Pair the phone as the owner’s.

boolean

Example

{
  "owner": true
}

Responses

200

The code.

application/json

object

code

required

Eight hexadecimal characters. Works once.

string

url

required

Opens the GurtOS web app (BOX_APP) with the code: <app>/pair#code=<code>&.... With remote access on, <app>/pair?box=<address>#<code>.

string

boxUrl

The box’s own pairing page, <address>/pair#<code>. There only when BOX_URL or remote access gives the box an address.

string

expiresAt

required

Five minutes after it was made.

string format: date-time

box

required

object

string

name

string

Example

{
  "code": "7f3a9c21",
  "url": "https://app.gurtos.com/pair#code=7f3a9c21&lan=box.local%3A7700&n=gurt-3f9a1c",
  "boxUrl": "http://box.local:7700/pair#7f3a9c21",
  "expiresAt": "2026-10-24T09:17:03.000Z",
  "box": {
    "id": "gurt-3f9a1c",
    "name": "gurt-3f9a1c"
  }
}

403

The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.

application/json

object

error

required

What went wrong

string

Example

{
  "error": "only this computer's own screen or the owner's paired device can do this"
}