Upsert Plugin
/pluginsCreates a server-assigned plugin or fully replaces an existing registration named by id. Every write requires Idempotency-Key; replacement requires the last observed strong If-Match.
A connection identity is host-assigned from authenticated principal, client and transport; an occupied scope cannot be created again without naming its existing id and etag. Replaying a committed write returns the retained entity without readmitting, disconnecting or altering its live transport connection. Credentials are never returned.
External WEBSOCKET and HTTP providers submit the connection branch with a public V2 manifest before connecting or discovering routes. The connection branch is mutually exclusive with plugin and credential fields; its identity is derived from the authenticated principal, client identity and transport. An absent or invalid declaration is a 400 INVALID_PLUGIN_MANIFEST and writes nothing.
Custom webservice and Apple push registrations use the plugin branch and also require manifestDocument. Their existing routing URL and credential fields remain authoritative; the public declaration cannot override deployment routing or credential values.
Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
Required scope
Any authenticated access token
Header parameters
- Idempotency-Key
stringRequired Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.
minLength: 1
maxLength: 255
- If-Match
string Required for a full replacement when the request identifies an existing resource. Send that resource's quoted strong etag from its last GET. A missing condition on a replacement returns 428 PRECONDITION_REQUIRED; a stale condition returns 412 PRECONDITION_FAILED. Omit this header when creating a new resource without an id. Wildcards are accepted only where the operation explicitly permits them.
minLength: 1
Request body
Fields
UpsertPluginRequestReturns
200
Canonical plugin stored atomically with its public declaration and credentials
Fields
UpsertPluginResponseResponse headers
- ETag
string Opaque strong entity tag of the returned resource version. Send it back in `If-Match` on the next mutation of the same resource.
Errors
400 BAD_REQUESTInvalid request payload
Check the request fields and any validation details, then correct the payload.
401 UNAUTHORIZEDAuthentication is required
Obtain a valid access token, then retry.
403 FORBIDDENThe caller may not mutate this plugin
Check the linked account and its permissions for the device or resource.
404 NOT_FOUNDThe existing plugin was not found
Verify the target identifier and that its endpoint or plugin route still exists.
409 CONFLICTThe key is in flight or the connection scope already exists
Check the device’s current mode or state. Retry only after the conflict is resolved.
412 PRECONDITION_FAILEDThe observed plugin revision is stale
Inspect the returned code and family and follow the error handling guide.
422 IDEMPOTENCY_KEY_REUSEDThe key was used for a different request
Correct the rejected value using the constraints in the error details or request schema.
428 PRECONDITION_REQUIREDIf-Match is required for replacement
Inspect the returned code and family and follow the error handling guide.
500 INTERNALInternal server error
Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.