API Reference

Pairing

Check app.capabilities for feature support and app.access plus host permissions for authorization. Examples use synthetic values; replace paths, IDs, inputs and filters before calling.

Device A
plainapp://pair?request=<URL-encoded JSON>
Device B

QR

QR payload

QR: A displays, B scans. LAN c-id identifies the sender; BLE uses its own transport. PAIR_CANCEL is optional.

Hover or tap a field
1 / 2

Synthetic snapshot at a fixed time; signatures and requestIds match. 192.0.2.0/24 is reserved for documentation. 8443 is the default HTTPS port; use the discovered port in real requests. These time-limited requests cannot be replayed as-is.

In PlainApp Desktop, managing a device begins with an explicit Trust decision if the device is new or its public key has changed. This step shows no comparison code and warns you if the key has changed. Next, during passwordless approval, compare the single code shown on both devices before approving on the other device. If you authenticated with a password, the other device may still ask for approval without showing a code.

Type Definitions

graphql
type Subscription {
  peersChanged: Boolean!
  pairingRequested: PairingRequestNotice!
  pairingCompleted: PairingCompletedNotice!
  pairingStarted: PairingProgressNotice!
  pairingFailed: PairingProgressNotice!
  pairingCanceled: PairingProgressNotice!
}

type Mutation {
  cancelPairing(peerId: ID!): Boolean!
  deletePeer(peerId: ID!): Boolean!
  pairPeer(peerId: ID!, input: PairPeerInput!): Boolean!
  respondToPairing(peerId: ID!, accepted: Boolean!): Boolean!
  unpairPeer(peerId: ID!): Boolean!
}

type Query {
  peerFileUrl(peerId: ID!, fileId: String!): String!
  peers: [Peer!]!
}

enum DeviceType {
	COMPUTER
	PHONE
	TABLET
	TV
	NAS
	OTHER
}

scalar Instant

input PairPeerInput {
	mode: PairingMode!
	password: String
}

type PairingCompletedNotice {
	deviceId: ID!
	deviceName: String!
	ip: String!
	port: Int
	deviceType: DeviceType
	requestId: String
}

enum PairingErrorCode {
	TIMEOUT
	REJECTED
	PASSWORD_REQUIRED
	INVALID_PASSWORD
	PEER_IDENTITY_CHANGED
	TOO_MANY_LOGIN_ATTEMPTS
	INTERNAL_ERROR
}

enum PairingMode {
	CHAT
	MANAGE
}

type PairingProgressNotice {
	verificationCode: String
	deviceId: ID!
	deviceName: String!
	error: PairingErrorCode
}

type PairingRequestNotice {
	fromIp: String!
	fromId: ID!
	fromName: String!
	deviceType: DeviceType!
	verificationCode: String!
	identityChanged: Boolean!
}

type Peer {
	id: ID!
	name: String!
	ip: String!
	status: PeerStatus!
	port: Int
	deviceType: DeviceType!
	createdAt: Instant!
	updatedAt: Instant!
	online: Boolean!
	managed: Boolean!
	key: String!
	publicKey: String!
	token: String!
}

enum PeerStatus {
	PAIRED
	UNPAIRED
	CHANNEL
}

Operations

subscription

peersChanged

Receive a change signal when peer records change.

graphql
subscription peersChanged {
  peersChanged
}
subscription

pairingRequested

Receive an incoming pairing request awaiting a decision.

graphql
subscription pairingRequested {
  pairingRequested { fromIp fromId fromName deviceType verificationCode identityChanged }
}
subscription

pairingCompleted

Receive notification that device pairing completed.

graphql
subscription pairingCompleted {
  pairingCompleted { deviceId deviceName ip port deviceType requestId }
}
subscription

pairingStarted

Receive notification that a pairing attempt started.

graphql
subscription pairingStarted {
  pairingStarted { verificationCode deviceId deviceName error }
}
subscription

pairingFailed

Receive notification that a pairing attempt failed.

graphql
subscription pairingFailed {
  pairingFailed { verificationCode deviceId deviceName error }
}
subscription

pairingCanceled

Receive notification that a pairing attempt was canceled.

graphql
subscription pairingCanceled {
  pairingCanceled { verificationCode deviceId deviceName error }
}
mutation

cancelPairing

Cancel the current pairing for the specified peer.

graphql
mutation cancelPairing($peerId: ID!) {
  cancelPairing(peerId: $peerId)
}
mutation

deletePeer

Delete a peer and its one-to-one chat history; retain a channel-only peer when a channel still references it.

graphql
mutation deletePeer($peerId: ID!) {
  deletePeer(peerId: $peerId)
}
mutation

pairPeer

Start chat pairing or management login with the specified peer; true acknowledges initiation.

graphql
mutation pairPeer($peerId: ID!, $input: PairPeerInput!) {
  pairPeer(peerId: $peerId, input: $input)
}
mutation

respondToPairing

Accept or reject the peer's pending pairing request or trust confirmation.

graphql
mutation respondToPairing($peerId: ID!, $accepted: Boolean!) {
  respondToPairing(peerId: $peerId, accepted: $accepted)
}
mutation

unpairPeer

Unpair a peer locally and clear its management access while retaining chat history.

graphql
mutation unpairPeer($peerId: ID!) {
  unpairPeer(peerId: $peerId)
}
query

peerFileUrl

Build a file download URL using the peer's current stored address.

graphql
query peerFileUrl($peerId: ID!, $fileId: String!) {
  peerFileUrl(peerId: $peerId, fileId: $fileId)
}
query

peers

List all saved peers, including paired, unpaired and channel-only records.

graphql
query peers {
  peers { id name ip status port deviceType createdAt updatedAt }
}