Skip to content
Macro DeckMacro Deck Docs

Pre-registration discovery

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

Reports supported versions, capability kinds, limits and timeouts so a plugin can decide whether and how to register before it holds any credential. No authentication required.

Responses

Section titled “Responses”

200

Section titled “200”

The protocol descriptor.

Media typeapplication/json

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginProtocolDescriptor.

object
supportedVersions
required
Array<integer>
capabilityKinds
required
Array<string>
limits
required

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginProtocolLimitsDescriptor.

object
maxMessageBytes
required
integer
maxAssetBytes
required
integer
maxAssetChunkBytes
required
integer
maxInboundQueueDepth
required
integer
maxOutboundQueueDepth
required
integer
queueHighWatermark
required
integer
queueLowWatermark
required
integer
maxConcurrentInvocations
required
integer
maxDeclaredCapabilities
required
integer
maxIdempotencyKeyLength
required
integer
maxErrorMessageLength
required
integer
maxErrorDetailEntries
required
integer
maxJsonDepth
required
integer
maxSessionsPerPlugin
required
integer
timeouts
required

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginProtocolTimeoutsDescriptor. Each field is a .NET TimeSpan serialized in its default “c” format (e.g. “00:00:10” for ten seconds).

object
handshake
required
string
defaultRequest
required
string
capabilityInvoke
required
string
assetUpload
required
string
keepAliveInterval
required
string
keepAliveTimeout
required
string
sessionResumeWindow
required
string
gracefulClose
required
string
pairing

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginPairingDescriptor. Absent from PluginProtocolDescriptor means the host does not support interactive pairing.

object
supported
required
boolean
requestLifetimeSeconds
required
integer
pollIntervalSeconds
required
integer
developerModeEnabled

Whether the host would accept a pairing request right now. Absent on a host that does not report it, which is not the same as false.

boolean
enrollment

Mirrors MacroDeck.Plugin.Protocol.Handshake.PluginEnrollmentDescriptor. Absent from PluginProtocolDescriptor means the host does not report anything about enrolment.

object
developerModeEnabled

Whether the host would accept an enrolment right now. Absent on a host that does not report it, which is not the same as false.

boolean
Examplegenerated
{
  "supportedVersions": [
    1
  ],
  "capabilityKinds": [
    "example"
  ],
  "limits": {
    "maxMessageBytes": 1,
    "maxAssetBytes": 1,
    "maxAssetChunkBytes": 1,
    "maxInboundQueueDepth": 1,
    "maxOutboundQueueDepth": 1,
    "queueHighWatermark": 1,
    "queueLowWatermark": 1,
    "maxConcurrentInvocations": 1,
    "maxDeclaredCapabilities": 1,
    "maxIdempotencyKeyLength": 1,
    "maxErrorMessageLength": 1,
    "maxErrorDetailEntries": 1,
    "maxJsonDepth": 1,
    "maxSessionsPerPlugin": 1
  },
  "timeouts": {
    "handshake": "example",
    "defaultRequest": "example",
    "capabilityInvoke": "example",
    "assetUpload": "example",
    "keepAliveInterval": "example",
    "keepAliveTimeout": "example",
    "sessionResumeWindow": "example",
    "gracefulClose": "example"
  },
  "pairing": {
    "supported": true,
    "requestLifetimeSeconds": 1,
    "pollIntervalSeconds": 1,
    "developerModeEnabled": true
  },
  "enrollment": {
    "developerModeEnabled": true
  }
}

403

Section titled “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.

Media typeapplication/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"
}