Edit an authorized subscription label

PATCH /{namespace}/{principalType}/{principalId}/subscriptions/{subscriptionId}

Changes the label only. Preserves the ID, original host arguments, query, target, generation and activation sequence. Refresh and unsubscribe continue to resolve the original host identity.

Required scope

subscription:write

Path parameters

namespacestringRequired: The namespace of the principal
principalTypestringRequired: The type of principal
principalIdstringRequired: The ID of the principal
subscriptionIdstringRequired: The ID of the subscription to delete

Request body

Fields

nameTypeValueRequired

Returns

200

Edit an authorized subscription label

Fields

idstringRequired

The unique identifier for the subscription

ownerstring

The owner of the subscription

nameTypeValue

queryQueryRequired

Shared Port OS query AST modeled as a recursive JSON graph supporting match, comparison, pattern, freeform, and boolean operators.

targetMessageTargetRequired

contextobject

Structured filter criteria for granular device event matching. Keys are dot-notation paths into the message (e.g., "header.namespace", "header.name"). Values are the expected values to match. All context entries must match for the subscription to fire. Omitting context matches all events.

statusstring

Event monitor lifecycle.

Allowed values: ACTIVE, PAUSED, SUSPENDED, EXPIRED, STOPPED.

reasonCodestring

Redacted stable lifecycle reason, when applicable.

expiresAtstring

Finite expiration; null means indefinite.

format: "date-time"

nullable: true

eventQueryProfilestring

Supported typed event query validation profile, when this is an event monitor.

Errors

400 BAD_REQUEST

Invalid request; stable code identifies the validation failure.

Check the request fields and any validation details, then correct the payload.

401 UNAUTHORIZED

Authentication required.

Obtain a valid access token, then retry.

403 FORBIDDEN

Resource authorization denied.

Check the linked account and its permissions for the device or resource.

404 NOT_FOUND

Resource inaccessible, missing or past retention.

Verify the target identifier and that its endpoint or plugin route still exists.

409 CONCURRENT_MODIFICATION

subscription_identity_immutable: request attempts to change monitoring identity. Existing binding and queued jobs are untouched.

Check the device’s current mode or state. Retry only after the conflict is resolved.

500 INTERNAL

Internal failure.

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.