Skip to content

Synchronize Plugin Routes via Discovery

← HTTP API reference
View source specification ↗
POST /discovery

Triggers 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

pluginIdentityClientIdentity

Identifies a plugin client by its type and unique identifier.

authLinkIdentitystring

The ID of the auth link

routesarray<ProviderDiscoveredRoute>Required

List of routes to synchronize. Route `id` values supplied here are not the stable plugin capability lookup surface after synchronization; match enumerated routes by `associatedPluginRouteId`.

groupRoutesarray<GroupRoute>

Group routes (maps, rooms, provider groups) to create or update, keyed by `pluginRouteId` within the plugin and auth link.

relationshipsarray<PluginDiscoveryRelationship>

Typed relationships between the reported routes and group routes.

Returns

200

Routes synchronized successfully

No response body.

Errors

400 BAD_REQUEST

Bad 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 UNAUTHORIZED

Unauthorized — missing or invalid bearer token

Obtain a valid access token, then retry.

403 FORBIDDEN

Forbidden — insufficient permissions

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

500 INTERNAL

Internal server error

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