Skip to content
Macro Deck Docs

Voluntary session teardown

DELETE
/api/plugins/sessions/{sessionId}
curl --request DELETE \
  --url https://example.com/api/plugins/sessions/example \
  --header 'Authorization: Bearer <token>'

Makes the session non-resumable at once.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
sessionId
required
string

Responses

Section titled “ Responses ”

204

Section titled “204”

The session was closed.

400

Section titled “400”

The request body does not match the expected shape.

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 ADB_NOT_ENABLED ADB_NOT_ALLOWED ADB_FAILED UI_RESOURCE_QUOTA_EXCEEDED PLUGIN_ICON_NOT_FOUND ICON_PACK_INVALID ICON_PACK_SYNC_NOT_ALLOWED ICON_NOT_FOUND
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"
}

401

Section titled “401”

Authentication failed. An unknown id and a wrong secret are indistinguishable in the response, the same oracle argument as device login.

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 ADB_NOT_ENABLED ADB_NOT_ALLOWED ADB_FAILED UI_RESOURCE_QUOTA_EXCEEDED PLUGIN_ICON_NOT_FOUND ICON_PACK_INVALID ICON_PACK_SYNC_NOT_ALLOWED ICON_NOT_FOUND
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"
}

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 ADB_NOT_ENABLED ADB_NOT_ALLOWED ADB_FAILED UI_RESOURCE_QUOTA_EXCEEDED PLUGIN_ICON_NOT_FOUND ICON_PACK_INVALID ICON_PACK_SYNC_NOT_ALLOWED ICON_NOT_FOUND
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"
}

429

Section titled “429”

Too many requests.

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 ADB_NOT_ENABLED ADB_NOT_ALLOWED ADB_FAILED UI_RESOURCE_QUOTA_EXCEEDED PLUGIN_ICON_NOT_FOUND ICON_PACK_INVALID ICON_PACK_SYNC_NOT_ALLOWED ICON_NOT_FOUND
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"
}

Headers

Section titled “Headers”
Retry-After
required
integer format: int32