Synchronize Plugin Routes via Discovery
/discoveryTriggers route synchronization for a plugin.
When a plugin connected to Port OS wants to report the routes available on it, it dispatches a discovery payload. The server reconciles the reported routes with its internal state.
For newly persisted synchronized routes, the server can assign a backend-generated, owner-scoped Port OS route id; a client-supplied route id in the discovery payload is advisory and is not the stable lookup surface for plugin capability parity. Consumers that need to match synchronized plugin or fixture routes after enumeration should use associatedPluginRouteId, which preserves the plugin-owned route identity.
Every route and group-route interface must name a capability interface and exact version from the capability-interface library, its configuration must conform to that interface's configuration schema (an omitted configuration is validated as an empty object), and any declared attribute must exist on the interface with a value that conforms to its attribute schema. Any nonconforming item rejects the whole request with 400; errors lists every rejected item keyed by pluginRouteId. Nothing is persisted.
Group routes and relationships are keyed by plugin-owned identity within the plugin and auth link and are created or updated, never removed because they are omitted. A pluginRouteId must be unique across routes and group routes (PLUGIN_ROUTE_ID_CONFLICT). Group-route members and relationship vertices must resolve to routes or group routes of the same plugin and auth link, committed or in the same request (UNRESOLVED_REFERENCE).
IS_PART_OF joins two group routes and is acyclic (RELATIONSHIP_CYCLE) with at most one parent per group route (MULTIPLE_PARENTS); CAN_CONTROL and LOCATED_IN join a route to a group route; self-edges and other shapes are INVALID_RELATIONSHIP. Only CAN_CONTROL carries interfaces, which must name interfaces and inbound messages the source route declares (MESSAGE_UNSUPPORTED). Relationship items are keyed by relationshipExternalId.
A newly reported group route creates its own endpoint group named after it; rediscovery keeps group IDs, merges and user renames.
Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
Required scope
Any authenticated access token
Request body
Fields
Returns
200
Routes synchronized successfully
No response body.
Errors
400 BAD_REQUESTBad request — invalid payload, or one or more routes or group routes do not conform to the capability-interface library
Check the request fields and any validation details, then correct the payload.
401 UNAUTHORIZEDUnauthorized — missing or invalid bearer token
Obtain a valid access token, then retry.
403 FORBIDDENForbidden — insufficient permissions
Check the linked account and its permissions for the device or resource.
500 INTERNALInternal server error
Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.