Poll a pairing request's status

GET

/api/plugins/pairing/{requestId}

const url = 'https://example.com/api/plugins/pairing/example';
const options = {method: 'GET'};

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

curl --request GET \
  --url https://example.com/api/plugins/pairing/example

An unknown or already-pruned request id deliberately answers 200 with status “expired” rather than 404, so the client state machine stays total and this endpoint is not an existence oracle.

Parameters

Path Parameters

requestId

required

string

Responses

200

The current status of the pairing request.

application/json

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginPairingStatusResponse.

object

status

required

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginPairingStatuses.All.

string

Allowed values: pending approved rejected expired

expiresAt

required

string format: date-time

Example

{
  "status": "pending"
}

403

The caller did not arrive on a loopback remote address. Plugin endpoints are served on both the public and private listeners, but only local processes may reach them. On the pairing endpoints, on POST /api/plugins/registration, and on POST /api/plugins/sessions for a plugin holding a development credential, this status also means Developer Mode is switched off in the desktop app - such a refusal carries “reason”: “developer_mode_disabled” in the error’s details, and GET /api/plugins/protocol reports the switch ahead of time.

application/json

Mirrors MacroDeck.Plugin.Protocol.Errors.ProtocolError.

object

code

required

One of the codes v1 speaks. Drift anchor - see x-macrodeck-error-codes above.

string

Allowed values: PROTOCOL_VERSION_UNSUPPORTED UNKNOWN_MESSAGE_TYPE MALFORMED_ENVELOPE INVALID_PAYLOAD UNAUTHENTICATED PLUGIN_ALREADY_REGISTERED SESSION_EXPIRED SESSION_NOT_RESUMABLE SESSION_REPLACED SESSION_NOT_FOUND CAPABILITY_UNSUPPORTED CAPABILITY_UNAVAILABLE PAYLOAD_TOO_LARGE ASSET_TOO_LARGE QUEUE_OVERFLOW RATE_LIMITED TIMEOUT CANCELLED CORRELATION_UNKNOWN DUPLICATE_IDEMPOTENCY_KEY INTERNAL_ERROR

message

required

Default English text keyed by code (MacroDeck.Plugin.Protocol.Errors.ProtocolErrorMessages). The UI localises from the code, not this string.

string

details

object

key

additional properties

string

retryable

required

boolean

Example

{
  "code": "PROTOCOL_VERSION_UNSUPPORTED"
}