Capability reference
A capability is one thing a device can do, such as turning on and off, dimming or streaming video. Each device lists the capabilities it supports, and every device with the same capability is used the same way.
To use a device, read which capabilities it has, then send it those capabilities' messages and read their attributes through the REST API or MCP.
Each capability can have three things: messages, attributes and configuration.
General capabilities report and change the basic state most devices share: power, connectivity, battery and remote control.
port1/systems/zero/capability-interfaces/powerPower turns a device on or off, reports its power state, and restarts devices that support rebooting.
Messages
Restart the endpoint. Advertise this message only when the provider supports rebooting the device.
Sent to the deviceFields
- (payload)
PowerInterfaceRebootMessage Restart the endpoint. Advertise this message only when the provider supports rebooting the device.
Turn the device off.
Sent to the deviceFields
No payload fields.
Turn the device on.
Sent to the deviceFields
No payload fields.
Attributes
Whether the device is on or off.
Fields
- value
stringRequired The power state of an endpoint
port1/systems/zero/capability-interfaces/power v1.0: attributes power: possible enum values for value Value Meaning ONThe device is on. OFFThe device is off.
port1/systems/zero/capability-interfaces/connectivityConnectivity tells you whether a connected device is reachable. Use its reported state to explain an unavailable device or decide when to retry an action.
Attributes
The quality of the device's network connection and its throughput in bits per second.
Fields
- quality
string - bitsPerSecond
integer
Signal measurements from the device's radios, such as signal strength (RSSI) and signal-to-noise ratio.
Fields
- values
array<RadioDiagnosticValue>Required A radio diagnostic measurement
- radioType
string - rssi
number - snr
number
- radioType
Whether Port OS can currently reach the device (OK or UNREACHABLE).
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/connectivity v1.0: attributes reachability: possible enum values for value Value Meaning OKThe device is reachable. UNREACHABLEThe device cannot currently be reached.
port1/systems/zero/capability-interfaces/batteryBattery reports a connected device's charge level and battery health. Use it to show when a device needs charging or a replacement battery.
Attributes
The battery level of the device and a report of its condition.
Fields
- level
numberRequired minimum: 0
maximum: 100
- health
string Reported battery condition.
port1/systems/zero/capability-interfaces/battery v1.0: attributes battery: possible enum values for health Value Meaning OKThe device is reachable. LOW— CRITICAL—
port1/systems/zero/capability-interfaces/percentagePercentage controls set or adjust a percentage and report the current value. Use them for connected controls expressed as a proportional level.
Messages
Raise or lower the percentage by an amount relative to its current value.
Sent to the deviceFields
- percentageDelta
numberRequired
Set the percentage to a specific value.
Sent to the deviceFields
- percentage
numberRequired
Attributes
The percentage the device is set to.
Fields
- value
numberRequired
port1/systems/zero/capability-interfaces/power-levelPower level sets or adjusts a device's output level and reports the current setting. Use it when a device supports more than a simple on/off control.
Messages
Raise or lower the power level by an amount relative to its current value.
Sent to the deviceFields
- powerLevelDelta
numberRequired
Set the power level to a specific value.
Sent to the deviceFields
- powerLevel
numberRequired
Attributes
The power level the device is set to.
Fields
- value
numberRequired
port1/systems/zero/capability-interfaces/remote-controlRemote control starts and ends control sessions and sends movement instructions. Use velocity, turning, and duration fields to request movement from a connected device.
Messages
End the remote control session.
Sent to the deviceFields
No payload fields.
Drive the device at a forward speed and turning rate for a set duration. Each move carries a sequence number so moves apply in order.
Sent to the deviceFields
- velocity
numberRequired Forward/backward speed
- omega
numberRequired Angular velocity for turning
- duration
integerRequired Duration in milliseconds
- seqNum
integerRequired Sequence number for ordering move commands
Start a remote control session so you can send move messages to the device.
Sent to the deviceFields
No payload fields.
Stop the device from moving during the remote control session.
Sent to the deviceFields
No payload fields.
Run an ordered list of movement instructions in a single session that Port OS manages for you.
Sent to the deviceFields
- instructions
array<MovementInstruction>Required Ordered list of movement instructions to execute in sequence
A movement instruction for remote control
- velocity
numberRequired Forward/backward speed
- omega
numberRequired Angular velocity for turning
- duration
integerRequired Duration in milliseconds
- velocity
Lighting capabilities set the brightness, color and color temperature of lights and recall lighting scenes.
port1/systems/zero/capability-interfaces/brightnessBrightness sets how bright a connected device should be and reports its current level. Use it to dim a light for the evening or restore a brighter setting for work.
Messages
Adjust brightness by a signed number of percentage points. The endpoint must advertise this message separately from set-brightness.
Sent to the deviceFields
- brightnessDelta
integerRequired minimum: -100
maximum: 100
Set the brightness of the device to a level.
Sent to the deviceFields
- brightness
integerRequired The brightness level to set
minimum: 0
maximum: 100
Attributes
The brightness level the device is set to.
Fields
- value
integerRequired The brightness level of an endpoint
minimum: 0
maximum: 100
port1/systems/zero/capability-interfaces/colorColor sets and reports the color of a connected device. Use it to coordinate lighting for a scene or let an assistant choose a new color.
Messages
Set the color of the device.
Sent to the deviceFields
- color
HsbColorRequired A color in HSB (Hue, Saturation, Brightness) color space
- hue
numberRequired Hue in degrees around the color wheel: 0 red, 120 green, 240 blue.
minimum: 0
maximum: 360
- saturation
numberRequired Saturation in percent: 0 is white, 100 is the full color.
minimum: 0
maximum: 100
- brightness
numberRequired Brightness in percent: 0 is dark, 100 is full brightness.
minimum: 0
maximum: 100
- hue
Attributes
The color the device is showing.
Fields
- color
HsbColorRequired A color in HSB (Hue, Saturation, Brightness) color space
- hue
numberRequired Hue in degrees around the color wheel: 0 red, 120 green, 240 blue.
minimum: 0
maximum: 360
- saturation
numberRequired Saturation in percent: 0 is white, 100 is the full color.
minimum: 0
maximum: 100
- brightness
numberRequired Brightness in percent: 0 is dark, 100 is full brightness.
minimum: 0
maximum: 100
- hue
port1/systems/zero/capability-interfaces/color-temperatureColor temperature adjusts a light between warmer and cooler tones. Set a temperature directly or increase and decrease it, then read the reported value in kelvin.
Messages
Lower the color temperature of the light by one step, for a warmer tone.
Sent to the deviceFields
No payload fields.
Raise the color temperature of the light by one step, for a cooler tone.
Sent to the deviceFields
No payload fields.
Set the color temperature of the light, in degrees Kelvin.
Sent to the deviceFields
- colorTemperatureInKelvin
integerRequired The colorTemperatureInKelvin property represents the color temperature in degrees Kelvin of an endpoint, and is used by endpoints that support tunable white light. Valid values range from 1,000 to 10,000 absolute Kelvin. The color values roughly map to: - warm white: 2000 - soft white: 2500 - white: 4000 - daylight white: 5500 - cool white: 7000
Attributes
The color temperature of the light, in degrees Kelvin.
Fields
- value
integerRequired
port1/systems/zero/capability-interfaces/sceneScenes activate or deactivate a predefined device scene. Use them to request a saved combination of settings from a connected integration.
Messages
Recall a scene on the group or endpoint that offers it. Names the scene to recall.
Sent to the deviceFields
- sceneId
stringRequired Identifier of the scene to activate, as listed in the available-scenes attribute
minLength: 1
Deactivate the scene that is currently active.
Sent to the deviceFields
No payload fields.
Attributes
The scene currently active on this group or endpoint. sceneId is omitted when no scene is active.
Fields
- sceneId
string Identifier of the active scene, one of the available-scenes ids
minLength: 1
The scenes that can be activated on this group or endpoint
Fields
- scenes
array<SceneInfo>Required Every scene the provider offers here, in provider order
A scene that can be activated
- id
stringRequired Scene identifier to pass to the activate message
minLength: 1
- name
stringRequired Human readable scene name
- id
Climate capabilities control thermostats, fans, water heaters and window coverings.
port1/systems/zero/capability-interfaces/thermostatThermostats set a target temperature and select a heating or cooling mode. Read the reported setpoints and operating mode to show the current settings.
Messages
Raise or lower the target temperature by an amount relative to its current value.
Sent to the deviceFields
- targetSetpointDelta
TemperatureSetpointRequired A temperature setpoint with value and scale
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: messages adjust-target-temperature: possible enum values for targetSetpointDelta.scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
- value
Set the target temperature, or the lower and upper setpoints when the thermostat works to a range.
Sent to the deviceFields
- targetSetpoint
TemperatureSetpoint A temperature setpoint with value and scale
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: messages set-target-temperature: possible enum values for targetSetpoint.scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
- value
- lowerSetpoint
TemperatureSetpoint A temperature setpoint with value and scale
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: messages set-target-temperature: possible enum values for lowerSetpoint.scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
- value
- upperSetpoint
TemperatureSetpoint A temperature setpoint with value and scale
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: messages set-target-temperature: possible enum values for upperSetpoint.scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
- value
Set the thermostat's mode.
Sent to the deviceFields
- mode
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: messages set-thermostat-mode: possible enum values for mode Value Meaning HEATRun in heating mode. COOLRun in cooling mode. AUTOSelect the operating mode automatically. ECO— OFFThe device is off.
Attributes
The lower temperature setpoint the thermostat holds when it works to a range, with its scale.
Fields
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: attributes lower-setpoint: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
The temperature the thermostat is set to hold, with its scale.
Fields
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: attributes target-setpoint: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
The mode the thermostat is in: heat, cool, auto, eco or off.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: attributes thermostat-mode: possible enum values for value Value Meaning HEATRun in heating mode. COOLRun in cooling mode. AUTOSelect the operating mode automatically. ECO— OFFThe device is off.
The upper temperature setpoint the thermostat holds when it works to a range, with its scale.
Fields
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/thermostat v1.0: attributes upper-setpoint: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
Configuration
port1/systems/zero/capability-interfaces/fan-controlFan control selects a fan mode and speed. Read the reported settings to check how a fan is running before changing them.
Messages
Set the fan's mode.
Sent to the deviceFields
- mode
stringRequired Fan mode
port1/systems/zero/capability-interfaces/fan-control v1.0: messages set-mode: possible enum values for mode Value Meaning OFFThe device is off. LOW— MEDIUM— HIGH— ONThe device is on. AUTOSelect the operating mode automatically. SMART—
Set the fan speed, as a percentage from 0 to 100.
Sent to the deviceFields
- speed
integerRequired Fan speed percentage (0-100)
minimum: 0
maximum: 100
Attributes
The mode the fan is running in.
Fields
- value
stringRequired Fan mode
port1/systems/zero/capability-interfaces/fan-control v1.0: attributes fan-mode: possible enum values for value Value Meaning OFFThe device is off. LOW— MEDIUM— HIGH— ONThe device is on. AUTOSelect the operating mode automatically. SMART—
The fan speed, as a percentage from 0 to 100.
Fields
- value
integerRequired Fan speed percentage (0-100)
minimum: 0
maximum: 100
Configuration
Fields
port1/systems/zero/capability-interfaces/water-heaterWater heaters set a temperature and operating mode. Read the temperature setpoint and mode to show the settings supplied by a connected heater.
Messages
Set the water heater's mode.
Sent to the deviceFields
- mode
stringRequired port1/systems/zero/capability-interfaces/water-heater v1.0: messages set-mode: possible enum values for mode Value Meaning OFFThe device is off. AUTOSelect the operating mode automatically. HEATRun in heating mode. ECO— BOOST—
Set the temperature the water heater should reach, in degrees Celsius.
Sent to the deviceFields
- temperature
numberRequired Temperature setpoint in degrees Celsius
minimum: 0
maximum: 100
Attributes
The mode the water heater is in.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/water-heater v1.0: attributes mode: possible enum values for value Value Meaning OFFThe device is off. AUTOSelect the operating mode automatically. HEATRun in heating mode. ECO— BOOST—
The temperature the water heater is set to reach, in degrees Celsius.
Fields
- value
numberRequired Temperature setpoint in degrees Celsius
minimum: 0
maximum: 100
Configuration
Fields
port1/systems/zero/capability-interfaces/window-coveringWindow coverings move to a requested lift or tilt percentage. Read their reported position to keep a shade or blind control in step with the device.
Messages
Move the covering to a lift position, in hundredths of a percent where 10000 is 100%.
Sent to the deviceFields
- liftPercent100thsValue
integerRequired Lift position in percent (0-10000, where 10000 = 100%)
minimum: 0
maximum: 10000
Move the covering to a tilt position, in hundredths of a percent where 10000 is 100%.
Sent to the deviceFields
- tiltPercent100thsValue
integerRequired Tilt position in percent (0-10000, where 10000 = 100%)
minimum: 0
maximum: 10000
Attributes
How far the covering is lifted and tilted, each as a percentage from 0 to 100.
Fields
- liftPosition
integerRequired Lift position percentage (0-100)
minimum: 0
maximum: 100
- tiltPosition
integer Tilt position percentage (0-100)
minimum: 0
maximum: 100
Configuration
Camera capabilities stream live video, take snapshots and report doorbell presses.
port1/systems/zero/capability-interfaces/cameraCameras provide streaming, event images, and camera controls. Start a stream, adjust pan and tilt when supported, or configure motion detection for the view you need.
Messages
Event image URL and provider token returned for a get-event-image request.
Sent by the deviceFields
- url
stringRequired format: "uri"
- token
stringRequired
Retrieve the image captured for a camera event, identified by its event ID and timestamp.
Sent to the deviceFields
- eventId
stringRequired The ID of the camera event to retrieve the image for
- eventTimestamp
string The timestamp of the camera event (ISO 8601 format)
format: "date-time"
Pan, tilt or zoom the camera. Pan and tilt range from -100 to 100, and zoom from 0 to 100.
Sent to the deviceFields
- pan
number Pan value (-100 to 100)
minimum: -100
maximum: 100
- tilt
number Tilt value (-100 to 100)
minimum: -100
maximum: 100
- zoom
number Zoom value (0 to 100)
minimum: 0
maximum: 100
Turn motion detection on or off for the camera.
Sent to the deviceFields
- enabled
booleanRequired Whether to enable motion detection
Start a live video stream from the camera using the streaming protocol you choose.
Sent to the deviceFields
- streamingProtocol
stringRequired Streaming protocol to use
Allowed values: RTSP, HLS, DASH, WEBRTC, OTHER.
- streamingUrl
string URL for streaming (if applicable)
format: "uri"
Stop the camera's live video stream.
Sent to the deviceFields
No payload fields.
Attributes
Whether motion detection is turned on for the camera.
Fields
- value
booleanRequired Whether motion detection is enabled
Configuration
Fields
port1/systems/zero/capability-interfaces/doorbellDoorbells emit a chime event. Use that event to start a notification or another flow when someone rings the bell.
Messages
A distinct doorbell press. A chime does not imply a door was opened.
Sent by the deviceFields
- value
stringRequired Allowed values: PRESSED.
port1/systems/zero/capability-interfaces/rtc-sessionRTC sessions initiate a connection using an offer and return an answer for the session. Follow disconnection events and close the session when the connection is no longer needed.
Messages
The answer generated for a real-time communication session, which completes the connection.
Sent by the deviceFields
- answer
RtcAnswerRequired An RTC session answer
- format
string Allowed values: SDP.
- value
RtcAnswerValue The content of the answer
- sdp
string The SDP answer session contents
- streamToken
string Provider token for the established stream
- streamExtensionToken
string Provider token used to extend the established stream
- expiresAt
string Provider-reported stream expiration
- streamUrl
string Provider stream URL when the answer is not SDP
- sdp
- format
Disconnect a real-time communication session by its session ID.
Sent to the deviceFields
- sessionId
stringRequired
The initiate session with offer message is used to initiate an RTC session between the client and an endpoint. The offer is expected to be a standard RTC SDP (standard description protocol) offer. The offer must contain all ICE candidates for the session to be established.
Sent to the deviceFields
- sessionId
stringRequired - sessionDomain
stringRequired The logical RTC session domain requested by the caller.
- offer
RtcOfferRequired An RTC session offer
- format
string Allowed values: SDP.
- value
string The SDP offer session contents
- format
- authorization
array<RtcSessionRoborockPinAuthorization> Message-specific session authorization entries required by the target endpoint.
discriminator: type
- RtcSessionRoborockPinAuthorization
RtcSessionRoborockPinAuthorization A Roborock session authorization entry carrying the PIN required to initiate a camera stream.
- type
stringRequired Allowed values: ROBOROCK_PIN.
- pin
stringRequired The Roborock PIN in dotted numeric format.
pattern: "^[0-9]+(\\.[0-9]+)*$"
- type
- RtcSessionRoborockPinAuthorization
- sessionDuration
integer The duration of the session in seconds. If not provided, the default is 60 seconds. If provided, the session will be terminated after the duration has elapsed. To reestablish the session, the client must initiate a new session with a new offer.
minimum: 1
maximum: 3600
Default:
60- autoAnswer
boolean
Reports that a real-time communication session has disconnected.
Sent by the deviceFields
No payload fields.
Configuration
Fields
- iceServers
array<RtcIceServer> Optional public STUN configuration passed to the browser's standard RTCIceServer interface. Omitted or empty means no ICE servers. Gathering starts only when a caller deliberately initiates a session. TURN and credentials are excluded.
The credential-free public STUN subset of the standard WebRTC RTCIceServer dictionary. URLs are discoverable configuration, never session credentials.
- urls
string | arrayRequired - string
stringRequired Public, credential-free STUN URI using the RFC 7064 stun:host[:port] form. This version supports DNS names and IPv4 hosts, with ports 1 through 65535. IPv6 literals, secure STUN, TURN, paths, queries and fragments are not supported by this configuration subset.
minLength: 6
maxLength: 256
pattern: "^stun:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?$"
- array
array<0>Required - Item
string Public, credential-free STUN URI using the RFC 7064 stun:host[:port] form. This version supports DNS names and IPv4 hosts, with ports 1 through 65535. IPv6 literals, secure STUN, TURN, paths, queries and fragments are not supported by this configuration subset.
minLength: 6
maxLength: 256
pattern: "^stun:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)*(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?$"
- Item
- string
- urls
- supportedStreams
array<RtcSessionSupportedStream> Discoverable media streams in SDP offer order. Directions describe the endpoint; the browser reverses SENDONLY and RECVONLY. Omitted means a video SENDONLY stream.
A discoverable RTC media stream supported by an endpoint.
- dataChannels
array<RtcDataChannel> Data channels the browser creates after media transceivers, using the standard RTCDataChannelInit options. Omitted means no data channels.
Standard WebRTC RTCDataChannelInit options plus the required label passed to createDataChannel. Channels are bidirectional.
port1/systems/zero/capability-interfaces/rtsp-sessionRTSP sessions open a camera connection and return its RTSP URI and optional SDP description. Close the session when the connection is no longer needed.
Messages
Start session.
Sent to the deviceFields
- sessionId
stringRequired Caller supplied session identifier.
minLength: 1
Start session response.
Sent by the deviceFields
- sessionId
stringRequired Session identifier.
minLength: 1
- uri
stringRequired RTSP stream URI.
format: "uri"
pattern: "^rtsps?://"
- sdp
string Optional SDP describing the stream.
minLength: 1
Stop session.
Sent to the deviceFields
- sessionId
stringRequired Session identifier to close.
minLength: 1
Stop session response.
Sent by the deviceFields
- sessionId
stringRequired Closed session identifier.
minLength: 1
port1/systems/zero/capability-interfaces/snapshotSnapshots request a captured view and return a snapshot response. Use them when an integration needs a single capture rather than a continuous live view.
Messages
Request a still image from the camera. responseFormat chooses how the image comes back: URL (default) is a short-lived Port OS link, BASE64 is the image bytes inline.
Sent to the deviceFields
- responseFormat
string How a request wants binary media (audio or image) returned. URL returns a short-lived signed URL hosted by Port OS (at most 10 minutes), never the vendor's own link. BASE64 returns the bytes inline as base64 and fails with a typed error above 10 MiB, in which case use URL.
Default:
URLAllowed values: URL, BASE64.
A camera still image, as a short-lived URL or inline base64 according to the request's responseFormat, with the time it was captured
Sent by the deviceFields
- image
MediaContentRequired One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
- timeOfSample
stringRequired format: "date-time"
Media capabilities play, search and control audio and video, and switch channels, inputs and apps.
port1/systems/zero/capability-interfaces/application-launcherApplication launchers start and stop applications on a connected device. Check the available applications and the current selection before choosing what to launch.
Messages
Open an application on the device. Optionally pass data for the application to start with.
Sent to the deviceFields
- catalogVendorId
integerRequired Catalog vendor ID
minimum: 0
- applicationId
stringRequired Application ID
- data
string Optional data to pass to the application
Close an application that is running on the device.
Sent to the deviceFields
- catalogVendorId
integerRequired Catalog vendor ID
minimum: 0
- applicationId
stringRequired Application ID
Attributes
The applications the device can launch, as reported by the device.
Fields
- applications
array<ApplicationInfo>Required An application reference
- catalogVendorId
integerRequired Catalog vendor ID
- applicationId
stringRequired Application ID
- catalogVendorId
The application that is open on the device now, identified by its catalog vendor and application ID.
Fields
- catalogVendorId
integer Catalog vendor ID
- applicationId
string Application ID
Configuration
port1/systems/zero/capability-interfaces/channelChannel controls select a channel or skip between channels on a connected device. Read the current channel to keep the interface in step with what is playing.
Messages
Tune the device to a channel.
Sent to the deviceFields
- channel
ChannelInfo A channel reference
- number
string - callSign
string - affiliateCallSign
string - uri
string
- number
Move forward or backward through the channel list by a number of channels.
Sent to the deviceFields
- channelCount
integerRequired
Attributes
The channel the device is tuned to, with its number, call sign and URI.
Fields
- number
string - callSign
string - affiliateCallSign
string - uri
string
port1/systems/zero/capability-interfaces/content-launcherContent launchers open content or a URL on a connected device. Use them to send a selected item to a screen or start the content a customer asked for.
Messages
Search for content on the device and open it, optionally starting playback automatically.
Sent to the deviceFields
- search
ContentSearch Content search criteria
- parameterList
array<ContentSearchParameter> A content search parameter
- type
stringRequired Allowed values: VIDEO, AUDIO, IMAGE, OTHER.
- value
stringRequired
- type
- parameterList
- autoPlay
boolean Whether to auto-play the content
Default:
true
Open content on the device from a URL.
Sent to the deviceFields
- contentUrl
stringRequired URL of the content to launch
format: "uri"
- displayString
string Display string for the content
- brandingInformation
BrandingInformation Content provider branding information
- providerName
string Provider name
- background
string Background image URL
format: "uri"
- logo
string Logo image URL
format: "uri"
- providerName
Configuration
port1/systems/zero/capability-interfaces/equalizerEqualizers adjust audio bands and select an equalizer mode. Read the current bands and mode to keep an audio control in step with the device.
Messages
Raise or lower the gain of equalizer bands relative to their current values.
Sent to the deviceFields
- bands
array<EqualizerBandDelta>Required An equalizer frequency band adjustment delta
- name
stringRequired Allowed values: BASS, MIDRANGE, TREBLE.
- valueDelta
integerRequired
- name
Set the gain of equalizer bands to specific values.
Sent to the deviceFields
- bands
array<EqualizerBand>Required An equalizer frequency band setting
- name
stringRequired Allowed values: BASS, MIDRANGE, TREBLE.
- value
integerRequired
- name
Select an equalizer preset.
Sent to the deviceFields
- mode
stringRequired
Attributes
The current gain of each equalizer band.
Fields
- values
array<EqualizerBand>Required An equalizer frequency band setting
- name
stringRequired Allowed values: BASS, MIDRANGE, TREBLE.
- value
integerRequired
- name
The equalizer preset the device is using.
Fields
- value
stringRequired
Configuration
port1/systems/zero/capability-interfaces/inputInput controls select or navigate between the inputs on a connected device. Read the current input to show which source is selected.
Messages
Switch the device to an input. Provide the input name or its index.
Sent to the deviceFields
- input
string Input name to select
- index
integer Input index to select
minimum: 0
Attributes
The input the device is using now, by name and index.
Fields
- value
stringRequired Current input name
- index
integer Current input index
minimum: 0
Configuration
port1/systems/zero/capability-interfaces/media-playerMedia players select media by its Port OS media ID, play supplied audio or a URI, and control playback. Read playback state and use only the commands supported by the connected player.
Messages
Audio data the player sends, with the stream ID, sequence, and whether it is the final chunk.
Sent by the deviceFields
- audioData
string Base64 encoded audio data
format: "base64"
- isFinal
boolean Whether the audio is the final chunk
Default:
false- sequenceId
integer Number of audio channels
- streamId
string Audio stream ID
Default:
default- text
string Audio text
Default:
- mimeType
string Audio MIME type
Default:
audio/ogg- rawBytes
string Audio raw bytes
format: "binary"
- duration
number Audio duration in seconds
minimum: 0
A chunk of an audio stream the player sends, with its stream ID and sequence, and whether it is the final chunk.
Sent by the deviceFields
- streamId
stringRequired Unique identifier for this audio stream
minLength: 1
- sequenceId
integerRequired Sequence ID for this audio stream
minimum: 0
- isFinal
booleanRequired Whether this is the final chunk in the stream
Default:
false- audioData
string Base64 encoded audio data
format: "base64"
- rawBytes
string Audio raw bytes
format: "binary"
Begin provider-defined fast-forward playback. This does not seek by a specific duration; use skip-forward or seek for a known position change.
Sent to the deviceFields
No payload fields.
Skip to the next item.
Sent to the deviceFields
No payload fields.
Pause playback.
Sent to the deviceFields
No payload fields.
Play a base64 encoded audio object on the endpoint. Requires audio output support; RTSP or SDP alone does not establish playback support.
Sent to the deviceFields
- audio
PlayableAudioRequired An audio object to play on an endpoint with audio output.
- data
stringRequired Base64 encoded audio, at most 10 MiB decoded.
format: "byte"
minLength: 4
maxLength: 13981016
pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"
- mimeType
stringRequired The audio MIME type, such as audio/wav or audio/mpeg.
pattern: "^audio/[a-zA-Z0-9.+-]+$"
- data
Play a media item by its media ID.
Sent to the deviceFields
- mediaId
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
Start or resume playback.
Sent to the deviceFields
No payload fields.
Play audio from a public HTTPS URI, optionally with a title.
Sent to the deviceFields
- uri
stringRequired Public HTTPS URI of the audio to play
format: "uri"
minLength: 1
- title
string Optional title for display or logging purposes
- sourceType
string URI transport semantics. Omission retains FILE behavior. LIVE_STREAM requires explicit live source support on the selected route; it must not be interpreted as a finite clip.
Allowed values: FILE, LIVE_STREAM.
- offsetInMilliseconds
integer Playback start position in milliseconds
minimum: 0
Default:
0
Go back to the previous item.
Sent to the deviceFields
No payload fields.
Rewind the current item.
Sent to the deviceFields
No payload fields.
Search for and play media by title or query using a service advertised by the endpoint. Omitting mediaType retains audio search behavior; video-only endpoints may default to video.
Sent to the deviceFields
- query
stringRequired Query to search for media content
minLength: 1
- provider
string Media service identifier. A provider enum value does not imply that every endpoint supports that service; use the endpoint's advertised provider lists.
Allowed values: SPOTIFY, AMAZON_MUSIC, APPLE_MUSIC, AUDIBLE, TUNE_IN, PANDORA, IHEART_RADIO, SIRIUSXM, DEEZER, TIDAL, YOUTUBE, NETFLIX, PRIME_VIDEO, DAILYMOTION.
- mediaType
string Media search domain. The endpoint must advertise support for the selected type.
Allowed values: AUDIO, VIDEO.
- timerSeconds
integer Optional provider playback timer in seconds.
minimum: 1
maximum: 86400
Jump to a position in the current item, in milliseconds.
Sent to the deviceFields
- positionMilliseconds
integerRequired Position to seek to in milliseconds
minimum: 0
Skip backward in the current item by a number of milliseconds.
Sent to the deviceFields
- deltaPositionMilliseconds
integer Number of milliseconds to skip backward
minimum: 0
Skip forward in the current item by a number of milliseconds.
Sent to the deviceFields
- deltaPositionMilliseconds
integer Number of milliseconds to skip forward
minimum: 0
Restart the current item from the beginning.
Sent to the deviceFields
No payload fields.
Stop playback.
Sent to the deviceFields
No payload fields.
Move the current playback session of the destination route's connected provider account to this one destination, preserving playing or paused state and media context. Select an advertised destination route. This affects that account's current session; it does not copy media, restart playback, transfer between providers or accounts, or fan out to group members. Read fresh source and destination state before and after dispatch to verify the move. An unavailable target requires an explicit choice of another destination.
Sent to the deviceFields
No payload fields.
Attributes
Latest admitted vendor observation for the latest physical-player clip attempt. This is separate from ordinary group playback. Missing, expired or revoked observations are unavailable, never inferred completion. Command acceptance alone supplies no value; physical clips do not support pause or resume.
Fields
- value
MediaClipObservationRequired Bounded passive telemetry for an exactly correlated physical-player command. This observation cannot authorize controls, retry playback or establish audible delivery.
- attemptId
stringRequired Port OS correlation for the latest admitted command, not a vendor media identifier or authorization token.
minLength: 1
maxLength: 2048
pattern: "^[^\\x00-\\x1F\\x7F-\\x9F]+$"
- status
stringRequired Vendor-reported physical clip lifecycle. SCHEDULED is command acceptance and is excluded. Unknown values and silence do not imply DONE.
Allowed values: ACTIVE, DONE, ERROR, DISMISSED, INTERRUPTED.
- errorCode
string Allowlisted Sonos clip error identifier. Omit unrecognized codes and vendor error text rather than exposing arbitrary payloads.
Allowed values: ERROR_AUDIO_CLIP_ID_NOT_FOUND, ERROR_AUDIO_CLIP_MEDIA_ERROR, ERROR_AUDIO_CLIP_PAUSE_CONTENT_FAILED.
- provenance
MediaClipProvenanceRequired Assurance of passive Sonos telemetry. Header authentication, exact issued-command correlation and ordering do not authenticate the event body. This is never proof of audible delivery or authority for automatic controls.
- integration
stringRequired Integration that supplied the observation.
Allowed values: SONOS.
- assurance
stringRequired Signed headers were verified against configured application credentials; the body remains unsigned.
Allowed values: PASSIVE_HEADER_AUTH.
- payloadIntegrity
booleanRequired Always false because Sonos does not sign the callback payload.
Allowed values: false.
- integration
- attemptId
Currently selected media metadata. Report only metadata supplied by the media provider; omission means unknown, not an empty playback session.
Fields
- value
MediaCurrentContentRequired Metadata for the media currently selected by a provider.
- mediaId
string Provider media identifier for the selected content.
- nativeIdentity
MediaSonosNativeIdentity Observed Sonos music-service coordinates for the current item, scoped to the reporting route and authorized connection. This identity is not a portable catalog ID, playable URL or authorization to play content. Preserve opaque values exactly; do not decode or log them.
- integration
stringRequired Integration defining this native identity format, independent of the source catalog provider.
Allowed values: SONOS.
- serviceId
string Exact service identifier reported by Sonos, when present.
minLength: 1
maxLength: 20
pattern: "^[^\\x00-\\x1F\\x7F-\\x9F]+$"
- objectId
stringRequired Exact opaque content identifier reported by Sonos, including its original case and percent escapes.
minLength: 1
maxLength: 256
pattern: "^[^\\x00-\\x1F\\x7F-\\x9F]+$"
- accountId
string Exact Sonos music-service account coordinate, when present. This is not a credential and must not authorize subsequent playback by itself.
minLength: 1
maxLength: 13
pattern: "^[^\\x00-\\x1F\\x7F-\\x9F]+$"
- integration
- title
string Display title supplied by the media provider.
- artist
string Artist or creator supplied by the media provider.
- artworkUrl
string HTTP or HTTPS URL of provider artwork. Consumers must treat this as untrusted display data, never executable content.
format: "uri"
- durationSeconds
number Reported duration of the selected media in seconds.
minimum: 0
- positionSeconds
number Observed playback position in seconds; not a command acknowledgement.
minimum: 0
- mediaId
Media identity observed on this route. Active false means the provider session is on another target; it does not prove the speaker is silent through other providers.
Fields
- active
booleanRequired - mediaId
string Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- contextMediaId
string Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- name
string - positionMs
integer Provider-observed position within the current media item in milliseconds. Omitted when unknown. Compare fresh observations with media identity and playback state; a track transition does not prove continuity.
minimum: 0
The playback speed as a multiplier, where 1.0 is normal speed.
Fields
- value
numberRequired Playback speed multiplier (1.0 = normal speed)
minimum: 0.1
maximum: 10
Whether the player is playing, paused or stopped.
Fields
- value
stringRequired The current playback state
Allowed values: PLAYING, PAUSED, STOPPED, LOADING, ERROR.
Configuration
Fields
- supportedMediaResources
array<SupportedMediaResource> Exact play-media URI combinations accepted by this route. Member or endpoint unions do not imply support by every route.
A provider, media type and resource-kind combination accepted by a control route.
- provider
stringRequired Media service identifier. A provider enum value does not imply that every endpoint supports that service; use the endpoint's advertised provider lists.
Allowed values: SPOTIFY, AMAZON_MUSIC, APPLE_MUSIC, AUDIBLE, TUNE_IN, PANDORA, IHEART_RADIO, SIRIUSXM, DEEZER, TIDAL, YOUTUBE, NETFLIX, PRIME_VIDEO, DAILYMOTION.
- provider
- supportedAudioProviders
array<string> Audio services accepted by search-and-play on this endpoint. These describe command support, not active subscriptions.
uniqueItems: true
- Item
string Media service identifier. A provider enum value does not imply that every endpoint supports that service; use the endpoint's advertised provider lists.
Allowed values: SPOTIFY, AMAZON_MUSIC, APPLE_MUSIC, AUDIBLE, TUNE_IN, PANDORA, IHEART_RADIO, SIRIUSXM, DEEZER, TIDAL, YOUTUBE, NETFLIX, PRIME_VIDEO, DAILYMOTION.
- Item
- supportedVideoProviders
array<items> Video services accepted by search-and-play on this endpoint. These describe command support, not installed applications or active subscriptions.
uniqueItems: true
- Item
string Media service identifier. A provider enum value does not imply that every endpoint supports that service; use the endpoint's advertised provider lists.
Allowed values: SPOTIFY, AMAZON_MUSIC, APPLE_MUSIC, AUDIBLE, TUNE_IN, PANDORA, IHEART_RADIO, SIRIUSXM, DEEZER, TIDAL, YOUTUBE, NETFLIX, PRIME_VIDEO, DAILYMOTION.
- Item
- defaultAudioProvider
string Default service for an audio search. Must be in supportedAudioProviders.
Allowed values: SPOTIFY, AMAZON_MUSIC, APPLE_MUSIC, AUDIBLE, TUNE_IN, PANDORA, IHEART_RADIO, SIRIUSXM, DEEZER, TIDAL, YOUTUBE, NETFLIX, PRIME_VIDEO, DAILYMOTION.
- defaultVideoProvider
string Default service for a video search. Must be in supportedVideoProviders.
Allowed values: SPOTIFY, AMAZON_MUSIC, APPLE_MUSIC, AUDIBLE, TUNE_IN, PANDORA, IHEART_RADIO, SIRIUSXM, DEEZER, TIDAL, YOUTUBE, NETFLIX, PRIME_VIDEO, DAILYMOTION.
- defaultQuality
string Default quality setting for media playback
Allowed values: LOW, MEDIUM, HIGH, LOSSLESS.
- supportedURISourceTypes
array<string> Exact source kinds accepted by play-uri on this route. With URI support, omission admits FILE only; an empty list admits none. LIVE_STREAM must be explicitly listed. This does not resolve provider catalog identities.
uniqueItems: true
- supportedAudioMimeTypes
array<string> Audio MIME types accepted by play-audio. Advertise play-audio only when audio output is supported.
- maxAudioDurationSeconds
integer Maximum encoded duration accepted by play-audio. Longer inputs are rejected without truncation.
minimum: 1
maximum: 86400
- audioPlaybackMode
string CLIP means finite immediate play-audio playback, which may interrupt or duck current content. QUEUE means finite controllable play-audio playback that replaces the current playback session. Neither mode appends to an existing queue, resolves a provider track, or establishes a live stream.
Allowed values: CLIP, QUEUE.
port1/systems/zero/capability-interfaces/media-playlistMedia playlists create and manage a collection of items to play. Add or remove items, retrieve a playlist, shuffle it, or ask the device to play it.
Messages
Add tracks to a playlist.
Sent to the deviceFields
- playlistId
stringRequired ID of the playlist to add tracks to
minLength: 1
- tracks
array<string>Required Track URIs to add to the playlist
- Item
string
- Item
Create a playlist, optionally with an initial list of tracks.
Sent to the deviceFields
- name
stringRequired Name of the playlist to create
minLength: 1
- tracks
array<string> Optional initial list of track URIs
- Item
string
- Item
Retrieve the contents of a playlist. Use the continuation token to read further pages.
Sent to the deviceFields
- playlistId
stringRequired ID of the playlist to retrieve
minLength: 1
- maxResults
integer minimum: 1
maximum: 50
Default:
20- nextToken
string Opaque continuation for the same playlist.
minLength: 1
List the connected customer's owned or followed playlists; use search-media for catalog search.
Sent to the deviceFields
- maxResults
integer minimum: 1
maximum: 50
Default:
20- nextToken
string minLength: 1
Play a playlist, optionally on a specific endpoint.
Sent to the deviceFields
- playlistId
stringRequired ID of the playlist to play
minLength: 1
- endpointId
string Optional target endpoint to play the playlist on
A bounded playlist page containing playable tracks or episodes.
Sent by the deviceFields
- playlistId
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- tracks
array<Track>Required Track information
- id
stringRequired Unique identifier for the track
minLength: 1
- name
stringRequired Track name
minLength: 1
- artists
array<Artist>Required Track artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- album
Album Track album when supplied by the provider. Omitted for sources such as YouTube videos that do not supply album metadata.
- id
stringRequired Unique identifier for the album
minLength: 1
- name
stringRequired Album name
minLength: 1
- artists
array<items>Required Album artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- id
- id
- episodes
array<PodcastEpisode>Required Provider-qualified podcast episode with selection metadata.
- id
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- name
stringRequired minLength: 1
- showId
string Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- releaseDate
string Provider release date; precision can be year, month or day.
- releaseDatePrecision
string Provider date precision.
- id
- nextToken
string minLength: 1
Provider acknowledgement for one playlist mutation. Re-read contents to verify the requested outcome. A partial result must not be retried automatically.
Sent by the deviceFields
- playlistId
stringRequired minLength: 1
- snapshotId
string Provider revision acknowledging the change, when returned.
- applied
booleanRequired Whether all requested steps were acknowledged. False can mean playlist creation succeeded but initial track insertion did not.
- detail
string
A page of the connected customer's playlists with exact resource IDs.
Sent by the deviceFields
- playlists
array<Playlist>Required - id
stringRequired Unique identifier for the playlist
minLength: 1
- name
stringRequired Playlist name
minLength: 1
- ownerId
string Provider-scoped owner identity, when supplied by the provider.
- ownerName
string Owner display name, useful for distinguishing owned and followed playlists.
- id
- nextToken
string minLength: 1
Remove a track from a playlist, by its index or its URI.
Sent to the deviceFields
- playlistId
stringRequired ID of the playlist to remove a track from
minLength: 1
- trackIndex
integerRequired Index of the track to remove (-1 to use trackUri instead)
- trackUri
string URI of the track to remove (used when trackIndex is -1)
Rename the selected playlist when the connected account owns it. Does not change visibility or contents.
Sent to the deviceFields
- playlistId
stringRequired Exact playlist resource ID copied from this account library.
minLength: 1
- name
stringRequired New playlist name.
minLength: 1
Shuffle the order of a playlist.
Sent to the deviceFields
- playlistId
stringRequired ID of the playlist to shuffle
minLength: 1
Remove only the selected playlist from the current account library. This does not permanently delete the provider playlist or change another account library.
Sent to the deviceFields
- playlistId
stringRequired Exact playlist resource ID copied from this account library.
minLength: 1
port1/systems/zero/capability-interfaces/media-searchMedia search requests content matching a search and returns audio media results. Use it to find an item before asking a player to play it.
Messages
The results of an audio search: matching artists, albums, tracks, playlists, shows and episodes.
Sent by the deviceFields
- artists
array<Artist>Required Artist results
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- albums
array<Album>Required Album results
Album information
- id
stringRequired Unique identifier for the album
minLength: 1
- name
stringRequired Album name
minLength: 1
- artists
array<items>Required Album artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- id
- tracks
array<Track>Required Track results
Track information
- id
stringRequired Unique identifier for the track
minLength: 1
- name
stringRequired Track name
minLength: 1
- artists
array<items>Required Track artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- album
Album Track album when supplied by the provider. Omitted for sources such as YouTube videos that do not supply album metadata.
- id
stringRequired Unique identifier for the album
minLength: 1
- name
stringRequired Album name
minLength: 1
- artists
array<items>Required Album artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- id
- id
- playlists
array<Playlist>Required Playlist results
- id
stringRequired Unique identifier for the playlist
minLength: 1
- name
stringRequired Playlist name
minLength: 1
- ownerId
string Provider-scoped owner identity, when supplied by the provider.
- ownerName
string Owner display name, useful for distinguishing owned and followed playlists.
- id
- shows
array<PodcastShow> Provider-qualified podcast series; read episodes before playback.
- id
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- name
stringRequired minLength: 1
- publisher
string
- id
- episodes
array<PodcastEpisode> Provider-qualified podcast episode with selection metadata.
- id
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- name
stringRequired minLength: 1
- showId
string Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- releaseDate
string Provider release date; precision can be year, month or day.
- releaseDatePrecision
string Provider date precision.
- id
- nextToken
string Opaque continuation for the same search; omit when exhausted.
minLength: 1
Inspect an exact media resource or traverse an album/show. Use get-playlist for playlist contents.
Sent to the deviceFields
- mediaId
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- maxResults
integer minimum: 1
maximum: 50
Default:
20- nextToken
string Opaque continuation for the same resource.
minLength: 1
Exact media resource details and a bounded page of its children.
Sent by the deviceFields
- mediaId
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- name
string - resourceKind
stringRequired Provider resource kind from the media URI.
- tracks
array<Track> Track information
- id
stringRequired Unique identifier for the track
minLength: 1
- name
stringRequired Track name
minLength: 1
- artists
array<Artist>Required Track artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- album
Album Track album when supplied by the provider. Omitted for sources such as YouTube videos that do not supply album metadata.
- id
stringRequired Unique identifier for the album
minLength: 1
- name
stringRequired Album name
minLength: 1
- artists
array<items>Required Album artists
Artist information
- id
stringRequired Unique identifier for the artist
minLength: 1
- name
stringRequired Artist name
minLength: 1
- id
- id
- id
- episodes
array<PodcastEpisode> Provider-qualified podcast episode with selection metadata.
- id
stringRequired Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- name
stringRequired minLength: 1
- showId
string Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- releaseDate
string Provider release date; precision can be year, month or day.
- releaseDatePrecision
string Provider date precision.
- id
- nextToken
string minLength: 1
Search for tracks, albums, artists, playlists, shows or episodes with a query.
Sent to the deviceFields
- query
stringRequired Freeform query string
- type
string Resource kind: track, album, artist, playlist, show or episode when advertised. Defaults to track
Default:
track- album
string Search by album name, can only be used when searching albums, and tracks
- artist
string Search by artist name, can only be used when searching artists, albums and tracks
- year
string Search by year, can only be used when searching albums, years, and tracks. You can pass a range like 1990-2000
- maxResults
integer Maximum results on one page.
minimum: 1
maximum: 50
Default:
20- nextToken
string Copy the opaque continuation from the previous result with the same query and filters.
minLength: 1
port1/systems/zero/capability-interfaces/recordingsRecordings list saved captures and expose recording download and deletion. Use pagination to browse the recordings supplied by a connected provider.
Messages
Delete recording.
Sent to the deviceFields
- recordingId
stringRequired Provider recording identifier.
minLength: 1
Delete recording response.
Sent by the deviceFields
- (payload)
RecordingsInterfaceDeleteRecordingResponseMessage Delete recording response.
Download recording.
Sent to the deviceFields
- recordingId
stringRequired Provider recording identifier.
minLength: 1
Download recording response.
Sent by the deviceFields
- uri
stringRequired Provider URL for downloading the recording.
format: "uri"
List recordings.
Sent to the deviceFields
- cursor
string Opaque cursor for the next page; omitted when there are no further results.
- maxResults
integer Maximum number of items to return.
minimum: 1
maximum: 1000
- from
string Inclusive start time.
format: "date-time"
- to
string Exclusive end time.
format: "date-time"
List recordings response.
Sent by the deviceFields
- items
array<Recording>Required Recordings in this page.
A stored recording.
- recordingId
stringRequired Provider identifier of the recording.
minLength: 1
- mediaId
string Exact provider resource identity. The canonical form is portos-media://portoperatingsystem.com/provider/media-type/resource-kind/resource-id, with no URI version. Spotify emits audio track, playlist, album, artist, show and episode identities. The prior authority remains readable. YouTube and YouTube Music share provider youtube, with video/video and video/channel resource kinds. Copy an ID returned by search or library discovery; do not send a search phrase as an ID. See https://portoperatingsystem.com/docs/media.
minLength: 1
pattern: "^(portos-media://(portpowered[.]com|portoperatingsystem[.]com)/[a-z][a-z0-9_-]*/(audio|video|image)/[a-z][a-z0-9_-]*/([^/?#\\s]|%[0-9A-Fa-f]{2})+|https?://[^\\s]+|portos://[^\\s]+)$"
- startedAt
string Recording start time.
format: "date-time"
- durationSeconds
number Recording duration in seconds.
minimum: 0
- recordingId
- nextCursor
string Opaque cursor for the next page; omitted when there are no further results.
port1/systems/zero/capability-interfaces/speakerSpeakers set or adjust volume and change mute state. Read the current volume and mute state to keep playback controls in step with the device.
Messages
Raise or lower the volume by an amount relative to its current value.
Sent to the deviceFields
- volumeDelta
numberRequired
Mute or unmute the speaker.
Sent to the deviceFields
- mute
booleanRequired
Set the speaker volume to a specific value.
Sent to the deviceFields
- volume
numberRequired minimum: 0
maximum: 100
Attributes
Whether the speaker is muted.
Fields
- value
booleanRequired
The speaker volume.
Fields
- value
numberRequired minimum: 0
maximum: 100
Sensor capabilities report measurements such as temperature, humidity, motion, air quality and pressure.
port1/systems/zero/capability-interfaces/air-quality-sensorAir quality reports the air-quality index measured by a device. Use the reading to understand conditions in a room and decide when to run ventilation or another automation.
Messages
Ask the device to report its current air quality reading.
Sent to the deviceFields
No payload fields.
Attributes
The air quality index the device reports, with the standard the value is measured in.
Fields
- value
integerRequired Air quality index value
minimum: 0
- standard
stringRequired Air quality standard
Allowed values: AIR_QUALITY_INDEX, PARTS_PER_MILLION_2_5, PARTS_PER_MILLION_10.
Configuration
port1/systems/zero/capability-interfaces/carbon-dioxide-concentration-sensorCarbon dioxide measurements report the concentration observed by a sensor, including its minimum and maximum readings. Use them to track changes in indoor conditions over time.
Attributes
The highest carbon dioxide concentration the sensor can measure.
Fields
- value
numberRequired Maximum measured value
The carbon dioxide concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
The lowest carbon dioxide concentration the sensor can measure.
Fields
- value
numberRequired Minimum measured value
port1/systems/zero/capability-interfaces/carbon-monoxide-concentration-sensorCarbon monoxide measurements report the concentration observed by a sensor, including its minimum and maximum readings. Use the reported values as input to monitoring and notification flows.
Attributes
The highest carbon monoxide concentration the sensor can measure.
Fields
- value
numberRequired Maximum measured value
The carbon monoxide concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
The lowest carbon monoxide concentration the sensor can measure.
Fields
- value
numberRequired Minimum measured value
port1/systems/zero/capability-interfaces/electrical-conductivity-sensorElectrical conductivity measurements report a sensor reading. Use the value and its declared units when displaying or comparing measurements.
Attributes
The electrical conductivity the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/event-detection-sensorEvent detection sensors report human presence and emit person-detected events. Use them to give an automation context about activity in a monitored area.
Messages
A distinct person detection occurrence, independent of cached presence state.
Sent by the deviceFields
- value
stringRequired Allowed values: DETECTED.
Attributes
Whether the device detects a person, and the methods (audio or video) used to detect them.
Fields
- value
stringRequired Allowed values: DETECTED, NOT_DETECTED.
- detectionMethods
array<string> - Item
string Allowed values: AUDIO, VIDEO.
- Item
Configuration
port1/systems/zero/capability-interfaces/flow-sensorFlow measurements report the flow observed by a sensor. Use the reading and its declared units to monitor changes in a connected system.
Attributes
The flow rate the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/formaldehyde-concentration-sensorFormaldehyde measurements report the concentration observed by a sensor. Use the reading and its declared unit when presenting environmental measurements.
Attributes
The formaldehyde concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/humidity-sensorHumidity sensors report relative humidity. Use the reading to display room conditions or provide input to a ventilation or humidifier flow.
Attributes
The relative humidity the sensor measures.
Fields
- value
numberRequired
port1/systems/zero/capability-interfaces/leaf-wetness-sensorLeaf wetness measurements report readings from a connected sensor. Use them as input when monitoring plants and growing conditions.
Attributes
The leaf wetness the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/light-sensorLight sensors report illuminance. Use the reading to understand ambient light and provide input to a lighting automation.
Attributes
The light level the sensor measures, in lux.
Fields
- value
numberRequired The illuminance value is a number between 1 and 65533. This attribute SHALL indicate the illuminance in Lux (symbol lx) as follows: • MeasuredValue = 10,000 x log10(illuminance) + 1, where 1 lx <= illuminance <= 3.576 Mlx, corresponding to a MeasuredValue in the range 1 to 0xFFFE. The MeasuredValue attribute can take the following values: • 0 indicates a value of illuminance that is too low to be measured, • MinMeasuredValue <= MeasuredValue <= MaxMeasuredValue under normal circumstances, • null indicates that the illuminance measurement is invalid. The MeasuredValue attribute is updated continuously as new measurements are made
port1/systems/zero/capability-interfaces/motion-sensorMotion sensors report detection state and emit motion-detected events. Use them to trigger a light, a notification, or another automation when movement is detected.
Messages
A distinct motion occurrence, independent of cached detection state.
Sent by the deviceFields
- value
stringRequired Allowed values: DETECTED.
Attributes
Whether the sensor detects motion.
Fields
- value
stringRequired Allowed values: DETECTED, NOT_DETECTED.
port1/systems/zero/capability-interfaces/nitrogen-dioxide-concentration-sensorNitrogen dioxide measurements report the concentration observed by a sensor. Use the value and its declared units in environmental monitoring.
Attributes
The nitrogen dioxide concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/ozone-concentration-sensorOzone measurements report the concentration observed by a sensor. Use the reading and its declared unit when displaying environmental conditions.
Attributes
The ozone concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/ph-sensorpH measurements report the reading supplied by a connected sensor. Use it when monitoring the conditions of a liquid or growing system.
Attributes
The pH the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/pm10-concentration-sensorPM10 measurements report the concentration observed by a particulate sensor. Use the reported value and unit when displaying air measurements.
Attributes
The PM10 particle concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/pm2-5-concentration-sensorPM2.5 measurements report the concentration observed by a particulate sensor. Use the reading to follow changes in measured air conditions.
Attributes
The PM2.5 particle concentration the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/pressure-sensorPressure measurements report the value supplied by a connected sensor. Use the value and its declared unit when monitoring pressure.
Attributes
The pressure the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/soil-moisture-sensorSoil moisture measurements report the reading supplied by a connected sensor. Use the value as input when monitoring growing conditions.
Attributes
The soil moisture the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
port1/systems/zero/capability-interfaces/temperature-sensorTemperature sensors report temperature and operation mode. Use the reading to display conditions or give a heating and cooling flow a measured input.
Attributes
The operation mode the temperature sensor reports.
Fields
- value
stringRequired
The temperature the sensor measures, with its scale.
Fields
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/temperature-sensor v1.0: attributes temperature: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
port1/systems/zero/capability-interfaces/wind-speed-sensorWind speed measurements report the reading supplied by a connected sensor. Use the value and its declared unit when displaying measured wind conditions.
Attributes
The wind speed the sensor measures, with its unit.
Fields
- value
MeasurementValueRequired A measurement value with optional null support
- value
numberRequired The measured value
- isNull
booleanRequired True if the measurement is invalid/null
Default:
false
- value
- unit
stringRequired Unit of measurement
Allowed values: LUX, PPM, PPB, PERCENT, PASCAL, LITERS_PER_MINUTE, PERCENT_VOLUME, PH, SIEMENS_PER_METER, METERS_PER_SECOND, DEGREES_CELSIUS, DEGREES_FAHRENHEIT.
Security capabilities lock doors, operate barriers and windows, and arm alarms and security panels.
port1/systems/zero/capability-interfaces/alarmAlarms ring, silence, or test a device's siren when supported. Read the alarm state to see whether the siren is active.
Messages
Sound the endpoint alarm. Requires an endpoint with an alarm actuator.
Sent to the deviceFields
- (payload)
AlarmInterfaceRingAlarmMessage Sound the endpoint alarm. Requires an endpoint with an alarm actuator.
Silence an alarm that is sounding. Requires an endpoint that can silence its alarm.
Sent to the deviceFields
No payload fields.
Run the alarm self-test so you can confirm the siren works. Requires an endpoint that supports alarm testing.
Sent to the deviceFields
No payload fields.
Attributes
Alarm state.
Fields
- active
booleanRequired Whether the audible alarm is currently sounding.
port1/systems/zero/capability-interfaces/barrier-controlBarrier control opens, closes, or positions a connected barrier. Read its position and state to check a garage door or gate before sending the next command.
Messages
Close the barrier.
Sent to the deviceFields
No payload fields.
Move the barrier to a position, as a percentage from 0 to 100.
Sent to the deviceFields
- position
integerRequired Barrier position percentage (0-100)
minimum: 0
maximum: 100
Open the barrier.
Sent to the deviceFields
No payload fields.
Attributes
How far a barrier, such as a garage door or gate, is open, as a percentage from 0 to 100.
Fields
- value
integerRequired Barrier position percentage (0-100)
minimum: 0
maximum: 100
Whether the barrier is open, closed, opening, closing or stopped.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/barrier-control v1.0: attributes barrier-state: possible enum values for value Value Meaning CLOSEDClosed state. OPENOpen state. OPENING— CLOSING— STOPPED—
port1/systems/zero/capability-interfaces/contact-sensorContact sensors tell you whether a door, window, or gate is open or closed. Use their reported state to check an entryway or trigger an automation when something is left open.
Attributes
Whether the contact sensor detects an opening. DETECTED means the sensor reports open (contact broken, for example an open door, window or garage door). NOT_DETECTED means it reports closed (contact made). This follows Alexa.ContactSensor and the SmartThings and Tuya mappings.
Fields
- value
stringRequired Allowed values: NOT_DETECTED, DETECTED.
port1/systems/zero/capability-interfaces/keypad-inputKeypad input sends a key to a connected device. Use it to build remote controls that send individual button presses.
Messages
Send a key press to the device, as a remote control would.
Sent to the deviceFields
- keyCode
stringRequired Key code to send
Allowed values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, UP, DOWN, LEFT, RIGHT, SELECT, HOME, BACK, EXIT, MENU, INFO, RED, GREEN, YELLOW, BLUE, CHANNEL_UP, CHANNEL_DOWN, VOLUME_UP, VOLUME_DOWN, MUTE, PLAY, PAUSE, STOP, FAST_FORWARD, REWIND, SKIP_FORWARD, SKIP_BACKWARD, RECORD, RECORD_STOP, POWER, SLEEP, WAKE.
Configuration
Fields
- supportedKeys
array<string> List of supported keys
- Item
string Allowed values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, UP, DOWN, LEFT, RIGHT, SELECT, HOME, BACK, EXIT, MENU, INFO, RED, GREEN, YELLOW, BLUE, CHANNEL_UP, CHANNEL_DOWN, VOLUME_UP, VOLUME_DOWN, MUTE, PLAY, PAUSE, STOP, FAST_FORWARD, REWIND, SKIP_FORWARD, SKIP_BACKWARD, RECORD, RECORD_STOP, POWER, SLEEP, WAKE.
- Item
port1/systems/zero/capability-interfaces/lockLocks accept lock and unlock commands and report their lock state. Use the reported state to check an entryway before requesting a change.
Messages
Lock the lock.
Sent to the deviceFields
No payload fields.
Unlock the lock.
Sent to the deviceFields
No payload fields.
Attributes
Whether the lock is locked or unlocked.
Fields
- value
stringRequired Allowed values: LOCKED, UNLOCKED, JAMMED.
port1/systems/zero/capability-interfaces/security-panelSecurity panels accept arm and disarm commands and report alarm and arming states. Use those reports to show the status supplied by a connected panel.
Messages
Arms the security panel. The body takes no fields: send an empty object ({}). Unknown fields are rejected. The simulator arms to ARMED_AWAY; read the resulting arm-state attribute for the current mode.
Sent to the deviceFields
No payload fields.
Disarms the security panel. The body takes no fields: send an empty object ({}). Unknown fields are rejected. Read the arm-state attribute to confirm it reports DISARMED.
Sent to the deviceFields
No payload fields.
Attributes
Whether the security panel is armed away, armed stay, armed night or disarmed.
Fields
- value
stringRequired Allowed values: ARMED_AWAY, ARMED_STAY, ARMED_NIGHT, DISARMED.
Whether the panel's burglary alarm is active.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/security-panel v1.0: attributes burglary-alarm: possible enum values for value Value Meaning OKThe device is reachable. ALARM—
Whether the panel's carbon monoxide alarm is active.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/security-panel v1.0: attributes carbon-monoxide-alarm: possible enum values for value Value Meaning OKThe device is reachable. ALARM—
Whether the panel is in an entry delay or an exit delay, and how many seconds the delay lasts.
Fields
- state
string Allowed values: ENTRY_DELAY, EXIT_DELAY, NONE.
- delayInSeconds
integer - playlistId
string - playOrder
array<SecurityPlayOrderItem> A play order item for security panel audio playback
- assetId
string - loopCount
integer - loopPauseInMilliseconds
integer
- assetId
Whether the panel's fire alarm is active.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/security-panel v1.0: attributes fire-alarm: possible enum values for value Value Meaning OKThe device is reachable. ALARM—
Whether the panel's siren is sounding, and the sounds it plays.
Fields
- state
string port1/systems/zero/capability-interfaces/security-panel v1.0: attributes siren-state: possible enum values for state Value Meaning ONThe device is on. OFFThe device is off. - playlistId
string - playOrder
array<SecurityPlayOrderItem> A play order item for security panel audio playback
- assetId
string - loopCount
integer - loopPauseInMilliseconds
integer
- assetId
Whether the panel's water alarm is active.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/security-panel v1.0: attributes water-alarm: possible enum values for value Value Meaning OKThe device is reachable. ALARM—
Configuration
Fields
port1/systems/zero/capability-interfaces/security-pinSecurity PINs create, update, query, and delete PIN records. Follow operation results and PIN reports when managing the records supported by a device.
Messages
Create an endpoint-scoped PIN. TEMPORARY requires both validity timestamps; PERMANENT forbids them. Validate increasing, nonexpired instants and declared restrictions before dispatch.
Sent to the deviceFields
- name
stringRequired - pin
stringRequired The code entered on the keypad. Leading zeros are kept.
writeOnly: true
- kind
stringRequired Allowed values: PERMANENT, TEMPORARY.
- validFrom
string format: "date-time"
- validUntil
string format: "date-time"
Delete a record within the authorized endpoint. Emit a correlated terminal result even when enumeration no longer includes the record.
Sent to the deviceFields
- id
stringRequired The PIN record to delete.
minLength: 1
Correlated safe PIN provisioning result. APPLIED requires vendor-confirmed completion, not dispatch acceptance. CREATE supplies recordId once assigned; UPDATE and DELETE retain the requested ID. FAILED requires a safe code; other statuses forbid code. Never include credentials or raw vendor errors.
Sent by the deviceFields
- correlationToken
stringRequired minLength: 1
- operation
stringRequired Allowed values: CREATE, UPDATE, DELETE.
- recordId
string minLength: 1
- provisioningStatus
stringRequired Allowed values: PENDING, APPLIED, FAILED.
- code
string Stable safe structured failure code. Never raw vendor text, credentials or response bodies.
minLength: 1
Bounded credential-free record page aligned with the pin-records attribute. Echo the query correlation token in the message header.
Sent by the deviceFields
- items
array<SecurityPinRecord>Required Endpoint-scoped PIN metadata without credentials. TEMPORARY requires both validity timestamps; PERMANENT forbids them. Provisioning status is distinct from observation freshness.
- id
stringRequired minLength: 1
- name
stringRequired - kind
stringRequired Allowed values: PERMANENT, TEMPORARY.
- validFrom
string format: "date-time"
- validUntil
string format: "date-time"
- provisioningStatus
stringRequired Allowed values: PENDING, APPLIED, FAILED.
- id
- nextToken
string Opaque continuation bound to endpoint, caller and query; omitted on the final page.
minLength: 1
Retrieve an endpoint-scoped PIN operation result by its original correlation token. Enforce caller and endpoint ownership. Return pin-operation-result, preserving the original operation correlation token in its payload and using this query's correlation token in the response header.
Sent to the deviceFields
- correlationToken
stringRequired minLength: 1
Query a bounded endpoint-scoped PIN record page. Requires message-send permission. Continuations bind caller, endpoint and page size; return pin-records-report with the request correlation token in its header.
Sent to the deviceFields
- maxResults
integer minimum: 1
maximum: 100
Default:
20- nextToken
string minLength: 1
Update an endpoint-scoped record. Require at least one change. Kind is immutable; validity changes require both timestamps and an authoritative TEMPORARY record.
Sent to the deviceFields
- id
stringRequired The PIN record to change.
minLength: 1
- name
string - pin
string The code entered on the keypad. Leading zeros are kept.
writeOnly: true
- validFrom
string format: "date-time"
- validUntil
string format: "date-time"
Attributes
Bounded endpoint-scoped PIN record page containing no credentials. Permanent records omit validity bounds; temporary records include both. Provisioning status is separate from observation freshness.
Fields
- items
array<SecurityPinRecord>Required Endpoint-scoped PIN metadata without credentials. TEMPORARY requires both validity timestamps; PERMANENT forbids them. Provisioning status is distinct from observation freshness.
- id
stringRequired minLength: 1
- name
stringRequired - kind
stringRequired Allowed values: PERMANENT, TEMPORARY.
- validFrom
string format: "date-time"
- validUntil
string format: "date-time"
- provisioningStatus
stringRequired Allowed values: PENDING, APPLIED, FAILED.
- id
- nextToken
string Opaque continuation bound to endpoint, caller and query; omitted on the final page.
minLength: 1
Verified optional restrictions from endpoint configuration. Omit unknown restrictions; absence does not guarantee vendor acceptance.
Fields
- supportedKinds
array<string> uniqueItems: true
- Item
string Allowed values: PERMANENT, TEMPORARY.
- Item
- minLength
integer minimum: 0
- maxLength
integer minimum: 0
- maxPins
integer Maximum simultaneous PINs the device holds; 1 means a single-PIN lock. Omitted when unknown.
minimum: 1
- pattern
string
Configuration
Fields
port1/systems/zero/capability-interfaces/smoke-co-alarmSmoke and carbon monoxide detectors report detection state. Devices expose alarm controls through the alarm capability and charge level through the battery capability.
Attributes
The alarm state the smoke and carbon monoxide alarm reports.
Fields
- value
stringRequired Alarm state
Allowed values: NORMAL, SMOKE_ALARM, CO_ALARM, BOTH_ALARM, TEST_MODE, HARDWARE_FAULT, END_OF_LIFE.
port1/systems/zero/capability-interfaces/windowWindows report their window state and lock state. Use those reports to check the status supplied by a connected window.
Attributes
Whether the window's lock is engaged.
Fields
- value
stringRequired Allowed values: LOCKED, UNLOCKED.
Whether the window is open, closed or tilted.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/window v1.0: attributes window-state: possible enum values for value Value Meaning OPENOpen state. CLOSEDClosed state. TILTED—
Location capabilities report where a device or person is and how spaces are laid out.
port1/systems/zero/capability-interfaces/locationLocation reports a connected resource's geolocation. Use it to show the position supplied by that resource.
Attributes
The geographic coordinates the device reports.
Fields
- coordinate
GeoCoordinateRequired A geographic coordinate
- latitudeInDegrees
numberRequired - longitudeInDegrees
numberRequired - accuracy
GeoAccuracy Geographic coordinate accuracy
- value
number - unit
string Allowed values: METERS.
- value
- latitudeInDegrees
port1/systems/zero/capability-interfaces/location-trackerLocation trackers start a locator and report its signal. Use them when helping a customer locate a connected item.
Messages
Start the tracker's locator signal so you can find it.
Sent to the deviceFields
No payload fields.
Attributes
Whether the tracker's locator signal, such as a beep or light, is on or off.
Fields
- value
stringRequired port1/systems/zero/capability-interfaces/location-tracker v1.0: attributes locator-signal: possible enum values for value Value Meaning ONThe device is on. OFFThe device is off.
port1/systems/zero/capability-interfaces/spatialDescriptive spatial declaration of a group route (home, floor/map, room or zone). The spatial interface declares no control messages; cleaning is sent to the robot endpoint.
Attributes
Whether this map or floor is the provider's currently loaded map (maps only)
Fields
- value
booleanRequired
Observed area of the group route in the coordinate system of its reference frame
Fields
- shape
SpatialPolygon | SpatialMultiPolygonRequired Area covered by a group route, as a polygon or multi-polygon
discriminator: type
- SpatialPolygon
SpatialPolygonRequired GeoJSON-like polygon: an exterior ring followed by optional interior rings (holes)
- type
stringRequired Allowed values: Polygon.
- coordinates
array<array<array<number>>>Required A closed ring of positions; the first and last positions are equal (GeoJSON linear ring)
- Item
array<number> A position as [x, y] or [x, y, z] in the frame's coordinate system
- Item
number
- Item
- Item
- type
- SpatialMultiPolygon
SpatialMultiPolygonRequired GeoJSON-like multi-polygon: a list of polygons, each a list of rings
- type
stringRequired Allowed values: MultiPolygon.
- coordinates
array<array<items>>Required - Item
array<array<number>> A closed ring of positions; the first and last positions are equal (GeoJSON linear ring)
A position as [x, y] or [x, y, z] in the frame's coordinate system
- Item
number
- Item
- Item
- type
- SpatialPolygon
- relativeToGroupId
string Canonical endpoint group whose frame the coordinates use
- relativeToGroupRouteId
string Provider group route whose coordinate system the coordinates use
- observedAt
stringRequired When the provider observed this geometry
format: "date-time"
Anchor point of the group route in its reference frame. It is a label anchor, not a navigation target.
Fields
- point
SpatialPointRequired GeoJSON-like point
- type
stringRequired Allowed values: Point.
- coordinates
array<number>Required A position as [x, y] or [x, y, z] in the frame's coordinate system
- Item
number
- Item
- type
- relativeToGroupId
string Canonical endpoint group whose frame the coordinates use
- relativeToGroupRouteId
string Provider group route whose coordinate system the coordinates use
- observedAt
stringRequired When the provider observed this position
format: "date-time"
Configuration
Text and speech capabilities generate text, embeddings and speech audio.
port1/systems/zero/capability-interfaces/embedding-generationEmbedding generation turns an input into an embedding and returns its URI. Use the result in integrations that work with vector representations of content.
Messages
The result of an embedding request: the location, format and MIME type of the generated embedding.
Sent by the deviceFields
- uri
stringRequired URL of the generated embedding resource
- format
string Format of the embedding (e.g., safetensors, onnx)
- mimeType
string MIME type of the embedding resource
Generate an embedding from an audio sample, optionally with reference text for the audio.
Sent to the deviceFields
- audioUrl
stringRequired URL or base64 data URI of the audio to generate an embedding from
- referenceText
string Optional reference text for the audio content
port1/systems/zero/capability-interfaces/speech-audio-generationSpeech audio generation turns text into speech audio with a model from the model catalog and returns it as a short-lived URL or inline base64, chosen with responseFormat. Choose a voice, and where the model supports it delivery tags or style instructions. Use the result when an integration needs an audio file it can pass to a player.
Messages
The speech audio synthesized by generate-speech, as a short-lived URL or inline base64 according to the request's responseFormat
Sent by the deviceFields
- audio
MediaContentRequired One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
Turn text into speech audio using a model and voice from the model catalog.
Sent to the deviceFields
- model
stringRequired Model identifier from the model catalog (query-models). An unknown model is rejected.
- text
stringRequired The text content to synthesize into speech audio
- voice
string Voice from the model catalog entry. Omit for the vendor default voice.
- styleInstructions
string Delivery direction separate from the spoken text, for models whose catalog entry supports it
- responseFormat
string How a request wants binary media (audio or image) returned. URL returns a short-lived signed URL hosted by Port OS (at most 10 minutes), never the vendor's own link. BASE64 returns the bytes inline as base64 and fails with a typed error above 10 MiB, in which case use URL.
Default:
URLAllowed values: URL, BASE64.
port1/systems/zero/capability-interfaces/speech-synthesizerSpeech synthesizers accept a request to speak. Use them to send spoken output to a connected device or integration.
Messages
Speak the input aloud on the device.
Sent to the deviceFields
- input
SpeechInputRequired Speech synthesis input
- type
stringRequired Allowed values: SSML, CANNED_TTS.
- ssml
string - cannedTtsStringId
string Provider-defined canned speech identifier; supported only by integrations advertising canned speech.
minLength: 1
- type
Configuration
port1/systems/zero/capability-interfaces/textText sends a text message to a connected component. Use it to pass written input between integrations.
Messages
Send text to the device or service.
Sent to the deviceFields
- text
stringRequired The text content of the message
minLength: 1
port1/systems/zero/capability-interfaces/text-streamText streams emit text as a stream of messages. Use the stream to consume output as it becomes available.
Messages
A chunk of streamed text, with its stream ID and sequence, and whether it is the final chunk.
Sent by the deviceFields
- streamId
stringRequired Unique identifier for this text stream
minLength: 1
- sequenceId
integerRequired Sequence ID for this text stream
minimum: 0
- isFinal
booleanRequired Whether this is the final chunk in the stream
Default:
false- text
stringRequired
Configuration
Fields
Media generation capabilities create images, music and transformed speech, and list the models that make them.
port1/systems/zero/capability-interfaces/image-generationImage generation turns a text prompt into an image with a model from the model catalog and returns it as a short-lived URL or inline base64, chosen with responseFormat. Choose an aspect ratio and resolution from the values the model supports.
Messages
Generates one image from a text prompt
Sent to the deviceFields
- model
stringRequired Model identifier from the model catalog (query-models). An unknown model is rejected.
- prompt
stringRequired Text describing the image to generate
- aspectRatio
string Aspect ratio as width:height, for example 16:9. Must be one the model lists in the model catalog.
- resolution
string Output resolution tier of a generated image. STANDARD is about 1 megapixel (a 1K tier), HIGH is about 2K and ULTRA is about 4K. A model lists the tiers it supports in the model catalog.
Allowed values: STANDARD, HIGH, ULTRA.
- responseFormat
string How a request wants binary media (audio or image) returned. URL returns a short-lived signed URL hosted by Port OS (at most 10 minutes), never the vendor's own link. BASE64 returns the bytes inline as base64 and fails with a typed error above 10 MiB, in which case use URL.
Default:
URLAllowed values: URL, BASE64.
The image produced by generate-image, as a short-lived URL or inline base64 according to the responseFormat of the request
Sent by the deviceFields
- image
MediaContentRequired One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
port1/systems/zero/capability-interfaces/model-catalogThe model catalog lists the models a provider offers for generation interfaces, with the prompting instructions, accepted settings and provenance of each. Query it before generating to choose a model and to see which voices, tags, aspect ratios or durations it supports.
Messages
The models matching query-models
Sent by the deviceFields
- models
array<ModelDescriptor>Required One model offered for one capability interface, with the configuration it supports and how to prompt it. Exactly the section that matches the capability interface is present (`speech`, `speechToSpeech`, `image` or `music`).
- capabilityInterface
stringRequired Canonical name of the capability interface the model serves, for example port1/systems/zero/capability-interfaces/speech-audio-generation.
- model
stringRequired The model identifier to pass as `model` in the interface generation message.
- displayName
stringRequired Human readable model name.
- promptingInstructions
stringRequired Free text on how to prompt the model, for example whether lyrics go in the prompt or in a separate field and which emotion or sound tags the model understands.
- maxPromptCharacters
integer Longest accepted text or prompt in characters, when the vendor documents one.
minimum: 1
- provenance
ModelProvenanceRequired Where the catalog entry came from.
- sourceUrl
stringRequired The vendor model page the entry was checked against.
- checkedOn
stringRequired The date (YYYY-MM-DD) the entry was last checked.
pattern: "^\\d{4}-\\d{2}-\\d{2}$"
- sourceUrl
- speech
ModelSpeechConfiguration Text to speech configuration.
- voices
array<string> Voices the model offers.
- Item
string
- Item
- defaultVoice
string The voice the vendor uses when `voice` is omitted, when the vendor documents one.
- customVoicesAccepted
boolean True when `voice` also accepts a voice name that is not in `voices`.
- soundTags
array<string> Emotion or sound tags the model documents, written exactly as they appear inline in the text, for example [whispering] or <laugh>. The list is documented examples, not a filter; the model may understand more.
- Item
string
- Item
- supportsStyleInstructions
boolean True when `styleInstructions` steers the delivery.
- voices
- speechToSpeech
ModelSpeechToSpeechConfiguration Speech to speech (voice conversion) configuration.
- inputAudio
AudioInputLimitsRequired What an audio input accepts.
- formats
array<string>Required Accepted media types of the input.
- Item
string
- Item
- minSeconds
number Shortest accepted duration, when the model has one.
minimum: 0
- maxSeconds
number Longest accepted duration, when the model has one.
minimum: 0
- maxBytes
integer Largest accepted input in decoded bytes.
minimum: 1
- formats
- speakerReference
ModelSpeakerReferenceRequired Reference audio of the voice to convert to.
- supported
booleanRequired True when `speakerReference` is accepted.
- limits
AudioInputLimits What an audio input accepts.
- formats
array<string>Required Accepted media types of the input.
- Item
string
- Item
- minSeconds
number Shortest accepted duration, when the model has one.
minimum: 0
- maxSeconds
number Longest accepted duration, when the model has one.
minimum: 0
- maxBytes
integer Largest accepted input in decoded bytes.
minimum: 1
- formats
- supported
- voices
array<string> Preset target voices; `voice` selects one when no speaker reference is given.
- Item
string
- Item
- inputAudio
- image
ModelImageConfiguration Image generation configuration.
- aspectRatios
array<string> Accepted values of `aspectRatio`, written as width:height.
- Item
string
- Item
- arbitraryAspectRatio
boolean True when any width:height ratio is accepted, not only `aspectRatios`.
- resolutions
array<string> Accepted values of `resolution`.
- Item
string Output resolution tier of a generated image. STANDARD is about 1 megapixel (a 1K tier), HIGH is about 2K and ULTRA is about 4K. A model lists the tiers it supports in the model catalog.
Allowed values: STANDARD, HIGH, ULTRA.
- Item
- defaultAspectRatio
string The ratio the vendor uses when `aspectRatio` is omitted, when it documents one.
- aspectRatios
- music
ModelMusicConfiguration Music generation configuration.
- supportsLyrics
booleanRequired True when `lyrics` is accepted as a separate field. When false, put the lyrics in the prompt.
- supportsGenres
booleanRequired True when `genres` is accepted. When false, name the genre in the prompt.
- genres
array<string> Accepted values of `genres`. Empty when `genres` is unsupported.
- Item
string
- Item
- supportsVocalGender
booleanRequired True when `vocalGender` is accepted.
- supportsDuration
booleanRequired True when `durationSeconds` is accepted.
- maxDurationSeconds
integer Longest accepted `durationSeconds`, when the model takes a duration.
minimum: 1
- maxLyricsCharacters
integer Longest accepted `lyrics`, when the vendor documents one.
minimum: 1
- supportsLyrics
- capabilityInterface
Lists the models a provider offers for its generation capability interfaces, with the configuration each supports and how to prompt it
Sent to the deviceFields
- capabilityInterface
string Canonical name of a generation capability interface, for example port1/systems/zero/capability-interfaces/image-generation. Omit to list every model.
port1/systems/zero/capability-interfaces/music-generationMusic generation turns a prompt, and for models that support it lyrics, genres and a vocal gender, into a song with a model from the model catalog and returns it as a short-lived URL or inline base64, chosen with responseFormat.
Messages
Generates a piece of music from a prompt and optional lyrics, genres and vocal gender. Fields the model does not support are rejected; the model catalog says which it supports.
Sent to the deviceFields
- model
stringRequired Model identifier from the model catalog (query-models). An unknown model is rejected.
- prompt
string Describes the music: mood, instrumentation, tempo and, for models without a lyrics field, the lyrics. Required unless the model takes lyrics and they are given.
- lyrics
string Lyrics to sing, for models whose catalog entry supports a separate lyrics field
- genres
array<string> Genres from the model catalog list
- Item
string
- Item
- vocalGender
string Preferred gender of the singing voice for generated music.
Allowed values: FEMALE, MALE.
- durationSeconds
integer Target length in seconds, for models whose catalog entry supports a duration
minimum: 1
- responseFormat
string How a request wants binary media (audio or image) returned. URL returns a short-lived signed URL hosted by Port OS (at most 10 minutes), never the vendor's own link. BASE64 returns the bytes inline as base64 and fails with a typed error above 10 MiB, in which case use URL.
Default:
URLAllowed values: URL, BASE64.
The music produced by generate-music, as a short-lived URL or inline base64 according to the responseFormat of the request
Sent by the deviceFields
- audio
MediaContentRequired One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
- lyrics
string The lyrics of the track when the model returns them
port1/systems/zero/capability-interfaces/speech-to-speechSpeech to speech converts the voice in a recording into another voice while keeping the words and delivery. Send the recording as base64 audio, choose a preset voice or a speaker reference, and receive the converted audio as a short-lived URL or inline base64, chosen with responseFormat.
Messages
Converts the voice in input audio to another voice, keeping the words and delivery. Both audio inputs carry base64 data, at most 5.5 MiB decoded each so that two of them fit the 16 MiB request body, and inputAudio at most 60 seconds; url inputs are rejected (a URL input would need host rules for caller-supplied addresses and is a follow-up).
Sent to the deviceFields
- model
stringRequired Model identifier from the model catalog (query-models). An unknown model is rejected.
- inputAudio
MediaContentRequired One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
- speakerReference
MediaContent One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
- voice
string A preset target voice from the model catalog entry, used when no speakerReference is given
- responseFormat
string How a request wants binary media (audio or image) returned. URL returns a short-lived signed URL hosted by Port OS (at most 10 minutes), never the vendor's own link. BASE64 returns the bytes inline as base64 and fails with a typed error above 10 MiB, in which case use URL.
Default:
URLAllowed values: URL, BASE64.
The converted speech produced by convert-speech, as a short-lived URL or inline base64 according to the responseFormat of the request
Sent by the deviceFields
- audio
MediaContentRequired One binary media result (audio or image). Exactly one of `data` (base64, inline) or `url` (a short-lived Port OS URL with its `expiresAt`) is present; the host rejects a result that carries both or neither. A plugin may return the vendor's fetchable `url` without `expiresAt`; the host always fetches it, republishes or inlines the bytes as the caller's `responseFormat` asks, and fills `byteLength`, so callers never see a vendor URL.
- mimeType
stringRequired The media type of the bytes.
Allowed values: audio/mpeg, audio/wav, audio/ogg, audio/flac, image/png, image/jpeg, image/webp.
- byteLength
integer Size of the decoded bytes. Always present on host responses.
minimum: 1
maximum: 26214400
- durationMs
integer Duration of audio in milliseconds, when known.
minimum: 0
- width
integer Image width in pixels, when known.
minimum: 1
- height
integer Image height in pixels, when known.
minimum: 1
- url
string Short-lived URL of the media (valid until `expiresAt`, at most 10 minutes).
- expiresAt
string When `url` stops working. Present with `url` on host responses.
format: "date-time"
- data
string Base64 encoded bytes, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
- mimeType
Appliance capabilities run kitchen, laundry and household appliances such as ovens, washers and vacuums.
port1/systems/zero/capability-interfaces/cleaning-modeCleaning types, suction levels and water flows the robot supports, refreshed on every discovery. set-cleaning-mode values outside these lists are rejected before dispatch.
Messages
Set whether the robot vacuums, mops or does both, optionally with a suction level and water flow. Omitted levels keep the current non-off value. Values outside the configured supported lists are rejected with 422 before dispatch.
Sent to the deviceFields
- mode
stringRequired What a cleaning robot does: vacuum only, mop only, or vacuum and mop together. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
Allowed values: VACUUM, MOP, VACUUM_AND_MOP, CUSTOM.
- suctionLevel
string Vacuum suction level, ordered from off to strongest. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
port1/systems/zero/capability-interfaces/cleaning-mode v1.0: messages set-cleaning-mode: possible enum values for suctionLevel Value Meaning OFFThe device is off. QUIET— BALANCED— TURBO— MAX— MAX_PLUS— CUSTOM— - waterFlow
string Mop water flow level, ordered from off to highest. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
port1/systems/zero/capability-interfaces/cleaning-mode v1.0: messages set-cleaning-mode: possible enum values for waterFlow Value Meaning OFFThe device is off. LOW— MEDIUM— HIGH— EXTREME— CUSTOM—
Attributes
Current cleaning type. CUSTOM when the robot uses a native mode with no equivalent value.
Fields
- value
stringRequired What a cleaning robot does: vacuum only, mop only, or vacuum and mop together. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
Allowed values: VACUUM, MOP, VACUUM_AND_MOP, CUSTOM.
Current suction level. CUSTOM when the robot uses a native mode with no equivalent value.
Fields
- value
stringRequired Vacuum suction level, ordered from off to strongest. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
port1/systems/zero/capability-interfaces/cleaning-mode v1.0: attributes suction-level: possible enum values for value Value Meaning OFFThe device is off. QUIET— BALANCED— TURBO— MAX— MAX_PLUS— CUSTOM—
Current water flow. CUSTOM when the robot uses a native mode with no equivalent value.
Fields
- value
stringRequired Mop water flow level, ordered from off to highest. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
port1/systems/zero/capability-interfaces/cleaning-mode v1.0: attributes water-flow: possible enum values for value Value Meaning OFFThe device is off. LOW— MEDIUM— HIGH— EXTREME— CUSTOM—
Configuration
Fields
- supportedSuctionLevels
array<string> Supported suction levels
uniqueItems: true
- Item
string Vacuum suction level, ordered from off to strongest. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
port1/systems/zero/capability-interfaces/cleaning-mode v1.0: configuration Configuration: possible enum values for supportedSuctionLevels[] Value Meaning OFFThe device is off. QUIET— BALANCED— TURBO— MAX— MAX_PLUS— CUSTOM—
- Item
- supportedWaterFlows
array<string> Supported water flows
uniqueItems: true
- Item
string Mop water flow level, ordered from off to highest. CUSTOM is a vendor-specific setting with no Port OS name (for example per-room settings); devices report it but do not accept it.
port1/systems/zero/capability-interfaces/cleaning-mode v1.0: configuration Configuration: possible enum values for supportedWaterFlows[] Value Meaning OFFThe device is off. LOW— MEDIUM— HIGH— EXTREME— CUSTOM—
- Item
port1/systems/zero/capability-interfaces/cooktopCooktops report their operational state. Use that state to show what the appliance is doing or supply context to an automation.
Attributes
The current operational state of the cooktop.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
port1/systems/zero/capability-interfaces/dishwasherDishwashers report their operational state. Use it to keep an appliance dashboard up to date or react when a reported state changes.
Attributes
The current operational state of the dishwasher.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
port1/systems/zero/capability-interfaces/extractor-hoodExtractor hoods report their fan speed. Use that state to show the current ventilation setting alongside other kitchen appliances.
Attributes
The extractor hood fan speed, as a percentage from 0 to 100.
Fields
- value
integerRequired Fan speed percentage (0-100)
minimum: 0
maximum: 100
port1/systems/zero/capability-interfaces/laundry-dryerLaundry dryers report their operational state. Use it to show the current appliance status or react to a change in a flow.
Attributes
The current operational state of the dryer.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
port1/systems/zero/capability-interfaces/laundry-washerLaundry washers report their operational state. Use it to keep a laundry dashboard in step with the appliance.
Attributes
The current operational state of the washer.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
port1/systems/zero/capability-interfaces/microwave-ovenMicrowave ovens report their operational state. Use that state to show what the appliance is currently doing.
Attributes
The current operational state of the microwave oven.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
port1/systems/zero/capability-interfaces/ovenOvens report their temperature. Use the reading to show the temperature supplied by a connected appliance.
Messages
Set the temperature the oven should reach.
Sent to the deviceFields
- targetSetpoint
TemperatureSetpointRequired A temperature setpoint with value and scale
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/oven v1.0: messages set-target-temperature: possible enum values for targetSetpoint.scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
- value
Attributes
The cooking mode the oven is in. Mode names are the provider's own, for example Bake or Broil.
Fields
- value
stringRequired minLength: 1
The current operational state of the oven.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
The temperature the oven is set to reach. The scale is the one the device reports its setpoint in.
Fields
- value
numberRequired - scale
stringRequired port1/systems/zero/capability-interfaces/oven v1.0: attributes target-temperature: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
The oven's current temperature, in the scale the device reports (Celsius or Fahrenheit).
Fields
- value
numberRequired Temperature in the reported scale
minimum: 0
maximum: 1112
- scale
stringRequired port1/systems/zero/capability-interfaces/oven v1.0: attributes temperature: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
port1/systems/zero/capability-interfaces/pet-feederPet feeders accept a command to trigger a feed. Use the command to start a feeding action from an interface or automation.
Messages
Dispense food for the pet, with an amount and unit.
Sent to the deviceFields
- feedAmount
integer Amount of food to feed the pet
minimum: 1
maximum: 100
- unit
string Unit of food to feed the pet
Default:
CUPSAllowed values: CUPS, GRAMS, POUNDS, OUNCES.
port1/systems/zero/capability-interfaces/pump-configuration-and-controlPump controls set a pump mode and speed. Read its capacity, mode, and status to keep a control interface in step with the pump.
Messages
Set the pump's mode.
Sent to the deviceFields
- mode
stringRequired Allowed values: STANDARD, CONSTANT_SPEED, CONSTANT_PRESSURE, PROPORTIONAL_PRESSURE, CONSTANT_FLOW, PROPORTIONAL_FLOW, CONSTANT_TEMPERATURE, AUTOMATIC.
Set the pump speed, as a percentage from 0 to 100.
Sent to the deviceFields
- speed
integerRequired Pump speed percentage (0-100)
minimum: 0
maximum: 100
Attributes
The pump's capacity.
Fields
- value
numberRequired Pump capacity
minimum: 0
The mode the pump is running in.
Fields
- value
stringRequired Allowed values: STANDARD, CONSTANT_SPEED, CONSTANT_PRESSURE, PROPORTIONAL_PRESSURE, CONSTANT_FLOW, PROPORTIONAL_FLOW, CONSTANT_TEMPERATURE, AUTOMATIC.
The current status of the pump.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
Configuration
port1/systems/zero/capability-interfaces/refrigeratorRefrigerators report their temperature. Use the reading to show the conditions supplied by the appliance.
Attributes
The refrigerator compartment's temperature, in the scale the device reports (Celsius or Fahrenheit).
Fields
- value
numberRequired Temperature in the reported scale
- scale
stringRequired port1/systems/zero/capability-interfaces/refrigerator v1.0: attributes temperature: possible enum values for scale Value Meaning CELSIUSTemperature in degrees Celsius. FAHRENHEITTemperature in degrees Fahrenheit.
port1/systems/zero/capability-interfaces/robotic-vacuum-cleanerRobotic vacuum cleaners start, pause, stop, and return to their dock. Set a cleaning mode and read the reported mode and operational state to follow a cleaning session.
Messages
Clean one or more rooms, in the requested order. Each entry is a canonical endpoint group the robot can control through a CAN_CONTROL relationship. More than one room requires the configuration to declare supportsMultiRoomCleaning; otherwise the request is rejected with MULTI_ROOM_UNSUPPORTED.
Sent to the deviceFields
- groupIds
array<string>Required Endpoint group IDs of the rooms to clean, in cleaning order
uniqueItems: true
- Item
string minLength: 1
- Item
- repeat
integer Number of cleaning passes per room; defaults to 1
minimum: 1
maximum: 3
Pause the current cleaning run.
Sent to the deviceFields
No payload fields.
Send the vacuum back to its dock.
Sent to the deviceFields
No payload fields.
Set the cleaning mode the vacuum uses.
Sent to the deviceFields
- mode
stringRequired Robot vacuum cleaning mode
port1/systems/zero/capability-interfaces/robotic-vacuum-cleaner v1.0: messages set-cleaning-mode: possible enum values for mode Value Meaning AUTOSelect the operating mode automatically. SPOT— EDGE— SINGLE_ROOM— CUSTOM—
Start a cleaning run.
Sent to the deviceFields
No payload fields.
Stop the current cleaning run.
Sent to the deviceFields
No payload fields.
Attributes
The cleaning mode the vacuum is set to.
Fields
- value
stringRequired Robot vacuum cleaning mode
port1/systems/zero/capability-interfaces/robotic-vacuum-cleaner v1.0: attributes cleaning-mode: possible enum values for value Value Meaning AUTOSelect the operating mode automatically. SPOT— EDGE— SINGLE_ROOM— CUSTOM—
The vacuum's current operational state, such as cleaning, docked or returning to its dock.
Fields
- value
stringRequired Operational state of a device. RETURNING_TO_DOCK means a robot is driving back to its dock; DOCKED means it is on the dock and not charging; DOCK_MAINTENANCE means it is on the dock while the dock services it (emptying the dust bin, washing or drying the mop), and it does not start cleaning until that finishes.
Allowed values: STOPPED, RUNNING, PAUSED, ERROR, CHARGING, DOCKED, RETURNING_TO_DOCK, DOCK_MAINTENANCE.
Configuration
Fields
Provider capabilities read and change calendars, contacts, files and reminders held by a connected account.
port1/systems/zero/capability-interfaces/calendar-providerCalendar providers list events from a connected calendar. Use the returned events to give an assistant schedule context or build an automation around an upcoming appointment.
Messages
Request to list events from a calendar provider
Sent to the deviceFields
No payload fields.
Response containing a list of events from a calendar provider
Sent by the deviceFields
- events
array<CalendarEvent>Required A calendar event
- eventId
stringRequired - title
string - location
string - description
string - allDay
boolean
- eventId
port1/systems/zero/capability-interfaces/contacts-providerContacts providers list contacts from a connected account. Use the returned records to give an assistant the contact information available to your integration.
Messages
Request to list contacts from a contacts provider
Sent to the deviceFields
No payload fields.
Response containing a list of contacts from a contacts provider
Sent by the deviceFields
- contacts
array<Contact>Required A contact entry
- contactId
stringRequired - firstName
string - lastName
string - companyName
string
- contactId
port1/systems/zero/capability-interfaces/filesystem-providerFilesystem providers list folders and photo albums and expose file download, upload, and deletion. Check the provider's supported commands before requesting an operation.
Messages
Delete file.
Sent to the deviceFields
- fileId
stringRequired Provider identifier for the file.
minLength: 1
The provider confirmed deletion of the requested file.
Sent by the deviceFields
- (payload)
FilesystemProviderInterfaceDeleteFileResponseMessage The provider confirmed deletion of the requested file.
Download file.
Sent to the deviceFields
- fileId
stringRequired Provider identifier for the file.
minLength: 1
Download file response.
Sent by the deviceFields
- uri
stringRequired Provider URL for downloading the file.
format: "uri"
- expiresAt
string Expiration of the download URL, if supplied by the provider.
format: "date-time"
Request to list photo albums from a filesystem provider
Sent to the deviceFields
- cursor
string Opaque cursor for the next page; omitted when there are no further results.
- maxResults
integer Maximum number of items to return.
minimum: 1
maximum: 1000
Response containing a list of photo albums from a filesystem provider
Sent by the deviceFields
- albums
array<PhotoAlbum>Required A photo album
- albumId
stringRequired - name
string - photoCount
integer
- albumId
- nextCursor
string Opaque cursor for the next page; omitted when there are no further results.
Request to list files and folders from a filesystem provider
Sent to the deviceFields
- folderId
string Optional folder ID to list contents of. Defaults to root if omitted.
- cursor
string Opaque cursor for the next page; omitted when there are no further results.
- maxResults
integer Maximum number of items to return.
minimum: 1
maximum: 1000
Response containing a list of files and folders from a filesystem provider
Sent by the deviceFields
- folderId
string Current folder identifier, including the provider root when returned. Use it as a destination for upload or move.
- items
array<StorageItem>Required A cloud storage item (file or folder)
- itemId
string - name
stringRequired - type
stringRequired Item type: FILE, FOLDER, or APP_LIBRARY
- size
integer File size in bytes
format: "int64"
- extension
string
- itemId
- nextCursor
string Opaque cursor for the next page; omitted when there are no further results.
Move one selected file into a folder without overwriting another item. The response returns the new selection for download or further operations.
Sent to the deviceFields
- fileId
stringRequired File selection copied from the current folder listing.
minLength: 1
- folderId
stringRequired Destination folder identifier copied from this provider listing.
minLength: 1
Verified file selection after the operation; use this fileId for subsequent reads or writes.
Sent by the deviceFields
- fileId
stringRequired minLength: 1
Rename a selected file without overwriting an existing name. Inspect the result and re-list before retrying an uncertain write.
Sent to the deviceFields
- fileId
stringRequired File selection copied from the current folder listing.
minLength: 1
- name
stringRequired New file name, including its extension, without path separators.
minLength: 1
Verified file selection after the operation; use this fileId for subsequent reads or writes.
Sent by the deviceFields
- fileId
stringRequired minLength: 1
Upload file.
Sent to the deviceFields
- folderId
stringRequired Destination folder identifier.
minLength: 1
- name
stringRequired File name.
minLength: 1
- mimeType
stringRequired File MIME type.
minLength: 1
- data
stringRequired Base64 encoded file content, at most 10 MiB decoded.
format: "byte"
maxLength: 13981016
pattern: "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"
Upload file response.
Sent by the deviceFields
- fileId
stringRequired Provider identifier of the uploaded file.
minLength: 1
port1/systems/zero/capability-interfaces/reminders-providerReminder providers list reminders from a connected account. Use the returned items to give an assistant task context or display an existing reminder list.
Messages
Create a reminder in a discovered list. Creation is sent once; refresh before retrying an uncertain result.
Sent to the deviceFields
- listId
stringRequired Discovered list identifier.
minLength: 1
- title
stringRequired Reminder title.
minLength: 1
- notes
string - dueDate
string Exact due instant in RFC3339 with an explicit UTC offset. Omitted on undated reminders.
format: "date-time"
- timeZone
string IANA time zone, for example America/Los_Angeles. Defaults to UTC for newly dated reminders.
- allDay
boolean Whether the supplied due date represents an all-day reminder.
The provider accepted the reminder change.
Sent by the deviceFields
- reminder
ReminderRequired A reminder and its current provider revision for guarded edits.
- reminderId
stringRequired - listId
stringRequired - title
stringRequired - notes
string - completed
booleanRequired - dueDate
string Exact due instant in RFC3339 with an explicit UTC offset. Omitted on undated reminders.
format: "date-time"
- timeZone
string IANA time zone, for example America/Los_Angeles. Defaults to UTC for newly dated reminders.
- allDay
boolean Whether the supplied due date represents an all-day reminder.
- revision
string Omitted when the provider does not supply a revision; writes require it.
- reminderId
Soft-delete a reminder using its last observed revision.
Sent to the deviceFields
- reminderId
stringRequired Reminder identifier.
minLength: 1
- revision
stringRequired Revision from the latest listing.
minLength: 1
The provider accepted soft deletion of the reminder.
Sent by the deviceFields
- (payload)
RemindersProviderInterfaceDeleteReminderResponseMessage The provider accepted soft deletion of the reminder.
List reminder lists and their reminders. Omit listId to enumerate all lists.
Sent to the deviceFields
- listId
string List identifier from a previous listing.
minLength: 1
- includeCompleted
boolean Default:
false- cursor
string Opaque next-page cursor.
- maxResults
integer minimum: 1
maximum: 1000
Reminder lists and one bounded page of reminders.
Sent by the deviceFields
- reminderLists
array<ReminderList>Required A reminder list
- listId
stringRequired - title
string
- listId
- reminders
array<Reminder>Required A reminder and its current provider revision for guarded edits.
- reminderId
stringRequired - listId
stringRequired - title
stringRequired - notes
string - completed
booleanRequired - dueDate
string Exact due instant in RFC3339 with an explicit UTC offset. Omitted on undated reminders.
format: "date-time"
- timeZone
string IANA time zone, for example America/Los_Angeles. Defaults to UTC for newly dated reminders.
- allDay
boolean Whether the supplied due date represents an all-day reminder.
- revision
string Omitted when the provider does not supply a revision; writes require it.
- reminderId
- nextCursor
string
Edit a reminder using its last observed revision; omitted fields are preserved.
Sent to the deviceFields
- reminderId
stringRequired Reminder identifier.
minLength: 1
- revision
stringRequired Revision from the latest listing.
minLength: 1
- title
string Replacement title.
minLength: 1
- notes
string - completed
boolean - dueDate
string Exact due instant in RFC3339 with an explicit UTC offset. Omitted on undated reminders.
format: "date-time"
- timeZone
string IANA time zone, for example America/Los_Angeles. Defaults to UTC for newly dated reminders.
- allDay
boolean Whether the supplied due date represents an all-day reminder.
- clearDueDate
boolean Set true to remove the due date. Cannot be combined with dueDate.
The provider accepted the reminder change.
Sent by the deviceFields
- reminder
ReminderRequired A reminder and its current provider revision for guarded edits.
- reminderId
stringRequired - listId
stringRequired - title
stringRequired - notes
string - completed
booleanRequired - dueDate
string Exact due instant in RFC3339 with an explicit UTC offset. Omitted on undated reminders.
format: "date-time"
- timeZone
string IANA time zone, for example America/Los_Angeles. Defaults to UTC for newly dated reminders.
- allDay
boolean Whether the supplied due date represents an all-day reminder.
- revision
string Omitted when the provider does not supply a revision; writes require it.
- reminderId
Discovery and access capabilities register endpoints, discover routes and authorize access to devices.
port1/systems/zero/capability-interfaces/control-route-groups-providerControl route groups organize several routes into a group. Create a group with its member routes or delete a group your integration no longer needs.
Messages
Request to delete a group based on its group ID.
Sent to the deviceFields
- pluginGroupRouteId
string The plugin group route ID to delete.
- memberRouteIds
array<string> The IDs of the routes that should exist in the group.
- Item
string
- Item
Request to delete a group based on its group ID.
Sent to the deviceFields
- pluginGroupRouteId
string The plugin group route ID to delete.
port1/systems/zero/capability-interfaces/control-routes-providerControl route providers carry dispatch results and attribute reports between an integration and Port OS. Use them to report acknowledgements, errors, deferred responses, and batches of messages.
Messages
Response to acknowledge a message was dispatched, it confirms that a message was dispatched, but not necessarily that it did anything. Consider this to happen on any infrared based device (TV remotes), where no ack is feasible.
Sent by the deviceFields
No payload fields.
Response to report attributes of a control route
Sent by the deviceFields
- items
array<ControlRouteItem>Required A control route item with associated plugin route and attributes
- associatedPluginRouteId
stringRequired - attributes
array<AttributeSchema>Required - namespace
stringRequired The namespace of the attribute
- name
stringRequired The name of the attribute
- version
stringRequired The version of the attribute
- value
objectRequired The value of the attribute
- sampledAt
string Actual observation time in UTC; omit when unknown. Request time is not a sample time.
format: "date-time"
- namespace
- unavailableAttributes
array<AttributeSelection> Exact attributes freshly found unavailable by a successful correlated native-group report-attributes read. Presence, including an empty list, is unsupported for endpoint, capability-query, proactive or uncorrelated reports. These identities carry no value or sample time; omission is not an unavailable acknowledgement. Upgrade consuming hosts before providers emit this field.
uniqueItems: true
The exact identity of an attribute requested from a provider, without an observed value.
- namespace
stringRequired minLength: 1
- name
stringRequired minLength: 1
- version
stringRequired minLength: 1
- namespace
- associatedPluginRouteId
Request to dispatch a batch of messages to a control route sent from port OS to the control routes provider
Sent to the deviceFields
- items
BatchMessageItemRequired A batch message dispatch item
- message
objectRequired The payload of the message to dispatch to the control route provider.
- message
Response to acknowledge a message was dispatched, it confirms that a message was dispatched, and that a confirmation of the result will be sent later on. We generate this message when the device is expected to respond some time later on, and we need to wait for the result. For the default behavior, we expect to wait up to a minute to handle low powered devices.
Sent by the deviceFields
No payload fields.
Response to acknowledge a message was dispatched, it confirms that a message was dispatched, and that the result was not successful.
Sent by the deviceFields
- error
DispatchError An error from a dispatch operation
- type
string The type of the error, an enum which denotes a specific type of error that belongs to a family of errors.
- family
string The family of the error, an enum which denotes a general set of issues similar to the http error set. Some examples are BAD_REQUEST, SYSTEM_ERROR, etc.
- code
string The code of the error, an opaque error code that can be given for debugging purposes.
- message
string The message of the error, a human readable message that describes the error.
- type
Request to report attributes of a control route sent from port OS to the control routes provider
Sent to the deviceFields
- items
array<ControlRouteReportItem>Required A control route report request with cookies and optional attribute selections. Omitted or empty attributes request all supported attributes.
- associatedPluginRouteId
stringRequired - cookies
object - attributes
array<AttributeSelection> The exact identity of an attribute requested from a provider, without an observed value.
- namespace
stringRequired minLength: 1
- name
stringRequired minLength: 1
- version
stringRequired minLength: 1
- namespace
- associatedPluginRouteId
Response to acknowledge a message was successfully dispatched, it confirms that a message was dispatched, and that the result was successful.
Sent by the deviceFields
No payload fields.
port1/systems/zero/capability-interfaces/endpoint-registryConfiguration for Port OS endpoint registry lifecycle notifications
Messages
Port OS emitted a durable endpoint metadata or enablement change. Delivery is best effort.
Sent by the deviceFields
- endpointId
stringRequired Full Port OS endpoint identifier.
- name
stringRequired Current endpoint name.
- type
stringRequired Current ontological endpoint type.
- enablement
stringRequired Whether Port OS permits messages to be sent to this endpoint.
Allowed values: ENABLED, DISABLED.
port1/systems/zero/capability-interfaces/route-discoveryRoute discovery reports the control routes available to an integration. Use its group commands to name a group or update the routes that belong to it.
Messages
Request to add members to a group route
Sent to the deviceFields
- groupRouteId
stringRequired The ID of the group route to add members to
- memberPluginRouteIds
array<string>Required List of plugin route IDs to add as members to the group route
- Item
string
- Item
Request to discover routes
Sent to the deviceFields
No payload fields.
Request to remove members from a group route
Sent to the deviceFields
- groupRouteId
stringRequired The ID of the group route to remove members from
- memberPluginRouteIds
array<string>Required List of plugin route IDs to remove as members from the group route
- Item
string
- Item
Provider report of discovered routes, group routes and their relationships. Plugin and auth-link identity come from the authenticated publisher context.
Sent by the deviceFields
- pluginIdentity
ClientIdentity Identifies a plugin client by its type and unique identifier.
- pluginType
stringRequired Allowed values: WEBSOCKET, HTTP, WEBSERVICE, APPLE_PUSH_NOTIFICATION, HOSTED_COMPUTE.
- pluginId
stringRequired The ID of the plugin
- pluginType
- authLinkIdentity
string The ID of the auth link the routes were discovered for.
- routes
array<ProviderDiscoveredRoute> Provider input before host synchronization assigns persisted route identity and ownership. Canonical provider facts reuse Route property definitions. The Go projection reuses the Route wire adapter; validation uses this input schema, not persisted Route. Host identity fields may be omitted or empty and never establish authenticated publisher or installation authority. Nonempty id and associatedEndpointId may select an existing authorized route during scoped rediscovery; newly created routes and endpoints receive host-assigned IDs.
- associatedPluginRouteId
stringRequired The stable plugin-owned route identifier associated with this Port OS route. For synchronized plugin capability contracts and fixture parity checks, use this field to match a route from enumeration back to the discovery payload.
minLength: 1
- externalId
string The external ID of the route given by the reporting system
- pluginProfileId
string Stable profile ID selected from the registered plugin declaration. Required for V2 plugin discovery; retained with the route for admission and presentation.
minLength: 1
- interfaces
array<items>Required List of interfaces supported by the route. These denote what the route is capable of performing such as turning off/on, etc.
- name
stringRequired The name of the interface
- version
string the version of the interface
- messages
array<ApplicationInterfaceMessage> Supported inbound message subset for the declared interface version. An omitted or empty list declares no supported messages; null also declares none. A supplied array contains distinct canonical names for implemented messages.
nullable: true
- name
stringRequired The name of the command
- name
- attributes
array<ApplicationInterfaceAttribute> Supported attribute subset. An omitted or empty list declares no supported attributes.
- name
stringRequired The name of the attribute
- value
object the value of the attribute, this is an opaque resource object, so it can be any type of struct.
- name
- configuration
object The configuration of the interface
- name
- ontologicalTypes
array<string>Required List of ontological types for the route. These are used mostly for customers to know what an endpoint is, like if its a lightbulb, or a speaker, etc.
- Item
string
- Item
- name
object The name of the route as a human readable string or a localizable asset. This is either a raw string or a localizable asset reference.
- type
stringRequired The type identifier of the name value, defined as plain when not defined.
- value
stringRequired the raw value of a plain name.
- type
- description
0 The description of the route as a human readable string or a localizable asset.
- type
stringRequired The type identifier of the name value, defined as plain when not defined.
- value
stringRequired the raw value of a plain name.
- type
- manufacturer
0 The manufacturer of the route as a human readable string or a localizable asset.
- type
stringRequired The type identifier of the name value, defined as plain when not defined.
- value
stringRequired the raw value of a plain name.
- type
- model
0 The model of the route as a human readable string or a localizable asset.
- type
stringRequired The type identifier of the name value, defined as plain when not defined.
- value
stringRequired the raw value of a plain name.
- type
- serialNumber
0 The serial number of the route as a human readable string or a localizable asset.
- type
stringRequired The type identifier of the name value, defined as plain when not defined.
- value
stringRequired the raw value of a plain name.
- type
- pluginCustomMetadata
object A set of custom metadata that the plugin uses and attaches to the route, this is meant specifically for the plugin to use.
- id
string Advisory value, including empty. Together with associatedEndpointId it may select an existing route within the authenticated scope. New persisted IDs are assigned by the host and validated by the separate persisted Route schema.
- associatedPluginId
string The ID of the associated plugin
- associatedAuthLinkId
string The ID of the associated auth link
- associatedEndpointId
string The ID of the associated endpoint
- associatedPluginRouteId
- groupRoutes
array<GroupRoute> A provider-reported group route (for example a vacuum map or room, a lighting room or a speaker group) as carried by discovery. It is shared by the route-discovery report message and `SynchronizationRequest.groupRoutes` so both decode to the same model.
- pluginProfileId
string Stable group-route profile ID selected from the registered V2 plugin declaration.
minLength: 1
- ontologicalTypes
array<string> Actual classifications of the native group route, constrained by its selected plugin profile for V2 discovery.
- Item
string
- Item
- pluginRouteId
stringRequired Plugin-owned stable identifier of the group route. Must be unique across routes and group routes within one plugin and auth link.
minLength: 1
- name
stringRequired The name of the associated group route
- interfaces
array<RouteInterface> - name
stringRequired The name of the interface
- version
string the version of the interface
- messages
array<ApplicationInterfaceMessage> Supported inbound message subset for the declared interface version. An omitted or empty list declares no supported messages; null also declares none. A supplied array contains distinct canonical names for implemented messages.
nullable: true
- name
stringRequired The name of the command
- name
- attributes
array<ApplicationInterfaceAttribute> Supported attribute subset. An omitted or empty list declares no supported attributes.
- name
stringRequired The name of the attribute
- value
object the value of the attribute, this is an opaque resource object, so it can be any type of struct.
- name
- configuration
object The configuration of the interface
- name
- memberPluginRouteIds
array<string> List of plugin route IDs that are members of this group route
uniqueItems: true
- Item
string
- Item
- pluginCustomMetadata
object Private plugin metadata (native map, segment or cloud room addressing) returned to the plugin on dispatch; never exposed as application data.
- pluginProfileId
- relationships
array<PluginDiscoveryRelationship> A provider-reported relationship between typed port resources. Identity is `externalId` within the reporting plugin and auth link; resubmitting the same `externalId` updates the relationship. Omission from a later synchronization is not a deletion instruction.
- externalId
stringRequired Plugin-owned stable identifier of the relationship.
minLength: 1
- type
stringRequired Typed relationship between port resources. `IS_PART_OF`: a resource is contained in a parent resource (acyclic). `CAN_CONTROL`: an endpoint or route can act on another resource with the listed interface messages; it never grants authorization. `LOCATED_IN`: an endpoint route is currently observed inside a group route; it is an observation, not membership. `MEMBER_OF`: an endpoint belongs to a group.
Allowed values: IS_PART_OF, CAN_CONTROL, LOCATED_IN, MEMBER_OF.
- source
PluginDiscoveryRelationshipVertexRequired One end of a discovered relationship, addressed by plugin-owned identity within the reporting plugin and auth link. Exactly one of `pluginRouteId` (a route), `groupPluginRouteId` (a group route), `endpointId` or `groupId` must be set.
- pluginRouteId
string The plugin route ID of a route reported in the same or an earlier synchronization.
minLength: 1
- groupPluginRouteId
string The plugin route ID of a group route reported in the same or an earlier synchronization.
minLength: 1
- endpointId
string The full ID of an endpoint owned by the reporting principal.
minLength: 1
- groupId
string The full ID of a group owned by the reporting principal.
minLength: 1
- pluginRouteId
- target
PluginDiscoveryRelationshipVertexRequired One end of a discovered relationship, addressed by plugin-owned identity within the reporting plugin and auth link. Exactly one of `pluginRouteId` (a route), `groupPluginRouteId` (a group route), `endpointId` or `groupId` must be set.
- pluginRouteId
string The plugin route ID of a route reported in the same or an earlier synchronization.
minLength: 1
- groupPluginRouteId
string The plugin route ID of a group route reported in the same or an earlier synchronization.
minLength: 1
- endpointId
string The full ID of an endpoint owned by the reporting principal.
minLength: 1
- groupId
string The full ID of a group owned by the reporting principal.
minLength: 1
- pluginRouteId
- interfaces
array<RelationshipInterface> Optional interface applicability; used by `CAN_CONTROL` to declare which messages the source supports on the target.
Capability-interface applicability of a relationship, for example the robotic-vacuum-cleaner messages a `CAN_CONTROL` edge supports on a room.
- name
stringRequired The capability interface namespace.
minLength: 1
- version
stringRequired The capability interface version.
minLength: 1
- messages
array<string> Message names of the interface the relationship applies to. An explicit empty array applies to no messages. Omission retains every message supported by the source interface.
uniqueItems: true
- Item
string minLength: 1
- Item
- name
- externalId
Request to set the name of a group route
Sent to the deviceFields
- groupRouteId
stringRequired The ID of the group route to set the name for
- name
RouteNameRequired A route name value
- type
stringRequired The type identifier of the name value, defined as plain when not defined
- value
stringRequired The raw value of a plain name or localizable asset reference
- type
Automation capabilities run flows and send notifications.
port1/systems/zero/capability-interfaces/flowsFlows run automations that can be initiated, paused, resumed, or terminated. Follow completion and acknowledgement events to understand the progress of a run.
Messages
Reports that a flow has finished, with its completion status, result and duration.
Sent by the deviceFields
- flowId
stringRequired Unique identifier for the completed flow
minLength: 1
- status
stringRequired Completion status
Allowed values: SUCCESS, FAILURE, CANCELLED, TIMEOUT.
- result
object Flow execution result
- duration
numberRequired Total execution duration in milliseconds
minimum: 0
- metadata
object Additional metadata for the completion
Start a flow, optionally with parameters, a priority and a timeout.
Sent to the deviceFields
- flowId
stringRequired Unique identifier for the flow to initiate
minLength: 1
- flowType
stringRequired Type of flow to initiate
minLength: 1
- parameters
objectRequired Flow initiation parameters
- priority
string Flow execution priority
Default:
NORMALAllowed values: LOW, NORMAL, HIGH, URGENT.
- timeout
integer Flow timeout in milliseconds
minimum: 1000
maximum: 86400000
- metadata
object Additional metadata for the flow initiation
Reports that a flow message was acknowledged.
Sent by the deviceFields
- flowId
stringRequired Unique identifier for the flow
minLength: 1
- messageId
stringRequired Unique identifier for the acknowledged message
minLength: 1
- ackId
stringRequired Unique identifier for this acknowledgment
minLength: 1
- status
stringRequired Acknowledgment status
Allowed values: RECEIVED, PROCESSED, FAILED.
- timestamp
stringRequired Acknowledgment timestamp
format: "date-time"
- metadata
object Additional metadata for the acknowledgment
Reports that a flow message was not acknowledged, with the reason.
Sent by the deviceFields
- flowId
stringRequired Unique identifier for the flow
minLength: 1
- messageId
stringRequired Unique identifier for the unacknowledged message
minLength: 1
- unackId
stringRequired Unique identifier for this unacknowledgment
minLength: 1
- reason
stringRequired Reason for unacknowledgment
Allowed values: TIMEOUT, ERROR, REJECTED, DUPLICATE.
- timestamp
stringRequired Unacknowledgment timestamp
format: "date-time"
- metadata
object Additional metadata for the unacknowledgment
Reports that a node in a flow has finished, with its status, result and the nodes that run next.
Sent by the deviceFields
- flowId
stringRequired Unique identifier for the flow
minLength: 1
- nodeId
stringRequired Unique identifier for the completed node
minLength: 1
- status
stringRequired Node completion status
Allowed values: SUCCESS, FAILURE, SKIPPED, TIMEOUT.
- result
object Node execution result
- duration
numberRequired Node execution duration in milliseconds
minimum: 0
- nextNodes
array<string> List of next node IDs to execute
- Item
string
- Item
- metadata
object Additional metadata for the node completion
Pause a running flow, optionally creating a checkpoint first.
Sent to the deviceFields
- flowId
stringRequired Unique identifier for the flow to pause
minLength: 1
- reason
stringRequired Reason for pausing
Allowed values: USER_REQUEST, RESOURCE_LIMIT, WAITING, MAINTENANCE.
- checkpoint
boolean Whether to create a checkpoint before pausing
Default:
true- metadata
object Additional metadata for the pause operation
Resume a paused flow, optionally from a checkpoint.
Sent to the deviceFields
- flowId
stringRequired Unique identifier for the flow to resume
minLength: 1
- checkpointId
string Checkpoint identifier to resume from (optional)
- metadata
object Additional metadata for the resume operation
Stop a running flow, optionally gracefully and with cleanup.
Sent to the deviceFields
- flowId
stringRequired Unique identifier for the flow to terminate
minLength: 1
- reason
stringRequired Reason for termination
Allowed values: USER_REQUEST, ERROR, TIMEOUT, COMPLETION, CANCELLATION.
- graceful
boolean Whether to perform graceful termination
Default:
true- cleanup
boolean Whether to perform cleanup operations
Default:
true- metadata
object Additional metadata for the termination
Configuration
port1/systems/zero/capability-interfaces/notificationNotifications can be triggered immediately or scheduled. Follow notification events to connect the delivery flow to the rest of an integration.
Messages
A notification delivered to target users, with its title, body, priority and delivery channels.
Sent by the deviceFields
- notificationId
string Unique identifier for this notification
minLength: 1
- title
stringRequired Notification title
minLength: 1
maxLength: 200
- body
stringRequired Notification body text
minLength: 1
maxLength: 2000
- priority
string Notification priority level
Allowed values: LOW, NORMAL, HIGH, URGENT.
- channels
array<string> Channels to send the notification through
- Item
string Allowed values: PUSH, EMAIL, SMS, IN_APP, WEBHOOK.
- Item
- targetUsers
array<string> List of user IDs to send the notification to
- Item
string
- Item
- metadata
object Additional metadata for the notification
Schedule recurring or future push notifications.
Sent to the deviceFields
- scheduleId
stringRequired Unique identifier for this schedule
minLength: 1
- notification
NotificationPayloadRequired Notification payload information
- title
stringRequired Notification title
minLength: 1
maxLength: 200
- body
stringRequired Notification body text
minLength: 1
maxLength: 2000
- priority
stringRequired Notification priority level
Allowed values: LOW, NORMAL, HIGH, URGENT.
- channels
array<string>Required Channels to send the notification through
- Item
string Allowed values: PUSH, EMAIL, SMS, IN_APP, WEBHOOK.
- Item
- targetUsers
array<string>Required List of user IDs to send the notification to
- Item
string
- Item
- title
- schedule
NotificationScheduleRequired Schedule configuration for notifications
- startTime
stringRequired When to start sending notifications
format: "date-time"
- endTime
string When to stop sending notifications (optional)
format: "date-time"
- cronExpression
string Cron expression for recurring notifications
- timezone
string Timezone for the schedule
Default:
UTC- repeatCount
integer Number of times to repeat (null for infinite)
minimum: 1
- interval
NotificationInterval Interval between notifications
- value
integerRequired Interval value
minimum: 1
- unit
stringRequired Interval unit
Allowed values: SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS.
- value
- startTime
- enabled
boolean Whether the schedule is enabled
Default:
true
Trigger a push notification immediately or when conditions are met.
Sent to the deviceFields
- triggerId
stringRequired Unique identifier for this trigger
minLength: 1
- triggerType
stringRequired Type of trigger
Allowed values: IMMEDIATE, SCHEDULED, EVENT_BASED, CONDITION_BASED.
- notification
NotificationPayloadRequired Notification payload information
- title
stringRequired Notification title
minLength: 1
maxLength: 200
- body
stringRequired Notification body text
minLength: 1
maxLength: 2000
- priority
stringRequired Notification priority level
Allowed values: LOW, NORMAL, HIGH, URGENT.
- channels
array<string>Required Channels to send the notification through
- Item
string Allowed values: PUSH, EMAIL, SMS, IN_APP, WEBHOOK.
- Item
- targetUsers
array<string>Required List of user IDs to send the notification to
- Item
string
- Item
- title
- conditions
NotificationConditions Conditions for triggering a notification
- eventType
string Type of event that triggers the notification
- eventData
object Data that must match for the event to trigger
- timeWindow
NotificationTimeWindow Time window for a notification trigger
- startTime
string format: "date-time"
- endTime
string format: "date-time"
- startTime
- eventType
- schedule
NotificationSchedule Schedule configuration for notifications
- startTime
stringRequired When to start sending notifications
format: "date-time"
- endTime
string When to stop sending notifications (optional)
format: "date-time"
- cronExpression
string Cron expression for recurring notifications
- timezone
string Timezone for the schedule
Default:
UTC- repeatCount
integer Number of times to repeat (null for infinite)
minimum: 1
- interval
NotificationInterval Interval between notifications
- value
integerRequired Interval value
minimum: 1
- unit
stringRequired Interval unit
Allowed values: SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS.
- value
- startTime