How to react to device events

Subscribe to a device event, such as motion at the front door, so your AI or your application can react when it happens.

What you need

• A Port OS account and a connected device that reports the event you want. A camera that detects motion is an example.
• An AI client connected with MCP, or an application that uses the REST API.
• The subscription:read and subscription:write permissions. Approve them when your AI client asks to connect. A connection approved before these permissions existed must be approved again.

Availability

Event subscriptions through MCP work only in ChatGPT today, and only for accounts on the waitlist. Other AI clients cannot create subscriptions yet. To join the waitlist, request access. The REST API manages subscriptions regardless of your AI client.

Subscribe through your AI

1. Ask your AI to watch for something. For example: "Tell me when someone comes to the front door."
2. Your AI finds the events your devices can report and creates a subscription. Port OS gives the subscription a name you can recognize.
3. When the event happens, Port OS tells your AI, and your AI reacts. For example, it checks the camera and notifies you.

Port OS verifies the connection with your AI before it turns a subscription on. A subscription does not expire unless you set an expiry.

Manage subscriptions through your AI

These MCP tools list and change the subscriptions you already have:

Tool	What it does
subscription_list	Lists your subscriptions with their IDs, names, source device, event and status. Pass cursor to read the next page.
subscription_inspect	Shows one subscription by its ID, including its filter and status.
subscription_label_edit	Renames one subscription. To change what is watched, create a new subscription and cancel the old one.
subscription_cancel	Stops one subscription by its ID. To watch again, create a new subscription.

Always use the exact ID from subscription_list. A name or a device ID does not identify a subscription.

For example, to stop watching the front door, ask your AI: "Stop telling me about the front door." Your AI lists your subscriptions, picks the matching one, and cancels it by ID.

Manage subscriptions with the REST API

Use these operations to manage subscriptions from your own application. Each one is documented in full in the REST reference.

Operation	Request	What it does
enumerateSubscriptions	GET /subscriptions	Lists subscriptions, or reads one when you pass id.
upsertSubscription	POST /subscriptions	Creates or updates a subscription. A subscription has a query that selects events and a target that receives them.
patchSubscription	PATCH /{namespace}/{principalType}/{principalId}/subscriptions/{subscriptionId}	Renames a subscription.
deleteSubscription	DELETE /{namespace}/{principalType}/{principalId}/subscriptions/{subscriptionId}	Stops a subscription.

A subscription can include a context filter. Each key is a path into the message, such as header.namespace or header.name, and each value is what the message must contain. A subscription fires only when every entry matches. Leave context out to receive every event.

Saving a subscription is eventually consistent. A saved subscription means Port OS registered it. It does not prove that your AI or application received an event. Read it back with GET /subscriptions and check that its status is ACTIVE.

Subscription status

Status	Meaning
ACTIVE	The subscription is watching.
PAUSED	The subscription is on hold.
SUSPENDED	Delivery is suspended. The reason code explains why.
EXPIRED	The subscription reached its expiry time.
STOPPED	You or the system cancelled the subscription.

Troubleshooting

• Your AI cannot create a subscription. Check that your AI client supports event subscriptions and that your account is on the waitlist.
• A request returns 403 insufficient_scope. The error names the missing permission. Reconnect your AI client and approve subscription:read and subscription:write.
• A subscription stopped after you reconnected your AI. Port OS stops subscriptions when you revoke the connection that created them. Create the subscription again.
• You get no events. Check that the subscription is ACTIVE, that the device is online, and that you can see the source device. See authorization rules.