@portpowered/reference-data 0.4.0 → 0.4.1

package/generated/public/docs/for-ai/operations/addEndpointGroupMembers.md

@@ -69,6 +69,8 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/AddEndpointGroupMembersRequest'
+        example:
+          memberEndpointIds: []
   responses:
     '202':
       description: Members addition accepted

package/generated/public/docs/for-ai/operations/authorizeDevice.md

@@ -52,6 +52,11 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/AuthorizeDeviceRequest'
+        example:
+          user_code: ABCD-EFGH
+          scopes:
+            - endpoint:read
+            - endpoint:write
   responses:
     '200':
       description: Device authorization successful
@@ -59,24 +64,35 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/AuthorizeDeviceResponse'
+          example:
+            success: true
     '400':
       description: Invalid request (e.g., missing user_code, invalid user_code, or invalid scopes)
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
     '401':
       description: Unauthorized (missing or invalid authentication token)
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
     '500':
       description: Internal server error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
   x-portos-delegated: false
   x-portos-resource-permission: false
   security:

package/generated/public/docs/for-ai/operations/completeOAuthConsent.md

@@ -56,6 +56,9 @@ post:
               type: boolean
             scope:
               type: string
+        example:
+          request_id: SERVER_ISSUED_PENDING_REQUEST_ID
+          approved: true
   responses:
     '200':
       description: Callback navigation URL containing code or denial and original state.
@@ -69,6 +72,8 @@ post:
               redirect_url:
                 type: string
                 format: uri
+          example:
+            redirect_url: http://127.0.0.1:8765/callback?code=SERVER_ISSUED_CODE&state=ORIGINAL_STATE
     '400':
       description: Invalid, expired or consumed request.
     '401':

package/generated/public/docs/for-ai/operations/createFlowNode.md

@@ -58,6 +58,8 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/FlowNode'
+          example:
+            id: port1/principals/example
     '400':
       description: Bad request — invalid request payload or validation failure.
       content:

package/generated/public/docs/for-ai/operations/createOAuthClient.md

@@ -52,6 +52,8 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/OAuthClientRegistrationRequest'
+        example:
+          clientName: port1/principals/example
   responses:
     '200':
       description: OAuth client created successfully
@@ -59,6 +61,9 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/CreateOAuthClientResponse'
+          example:
+            clientId: port1/principals/example
+            clientSecret: port1/principals/example
     '400':
       description: Invalid request payload
     '401':

package/generated/public/docs/for-ai/operations/createToken.md

@@ -58,6 +58,10 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/CreateTokenResponse'
+          example:
+            id: port1/principals/example
+            token: port1/principals/example
+            expires_at: '2026-10-08T12:00:00Z'
     '400':
       description: Invalid request (e.g. invalid subject, malformed body)
     '401':

package/generated/public/docs/for-ai/operations/createView.md

@@ -44,6 +44,12 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/UpsertViewRequest'
+        example:
+          title:
+            type: LIGHT
+            value: port1/principals/example
+          positions: []
+          widgets: []
   responses:
     '201':
       description: View created successfully

package/generated/public/docs/for-ai/operations/deleteEndpoint.md

@@ -37,7 +37,7 @@ delete:
         schema:
           $ref: '#/components/schemas/DeleteEndpointRequest'
         example:
-          id: port1/principals/user123/resources/abc-123
+          id: port1/principals/example/endpoints/light-1
   responses:
     '200':
       description: Endpoint deleted successfully

package/generated/public/docs/for-ai/operations/deleteFlowNode.md

@@ -52,6 +52,8 @@ delete:
             id:
               type: string
               description: The ID of the flow node to delete.
+        example:
+          id: port1/principals/example
   responses:
     '200':
       description: Flow node deleted successfully.

package/generated/public/docs/for-ai/operations/deleteRoute.md

@@ -37,7 +37,7 @@ delete:
         schema:
           $ref: '#/components/schemas/DeleteRouteRequest'
         example:
-          id: port1/principals/user123/resources/abc-123
+          id: port1/principals/example/routes/light-route
   responses:
     '200':
       description: Route deleted successfully

package/generated/public/docs/for-ai/operations/deviceAuthorize.md

@@ -1,6 +1,6 @@
 # deviceAuthorize
 
-POST `/auth/device_authorization`
+POST `/auth/device-authorization`
 
 OAuth2 Device Authorization
 
@@ -9,13 +9,13 @@ This API is used by your device to obtain authorization from the resource owner
 See the [OAuth device authorization docs for more](https://datatracker.ietf.org/doc/html/rfc8628).
 
 
-Uses the existing managed-client device flow. This endpoint is public, but validates its client and supported device grant; anonymous DCR clients support authorization_code and optional refresh_token, and cannot start the device flow.
+Uses the existing managed-client device flow. This endpoint is public, but validates its client and supported device grant; anonymous DCR clients support authorization_code and optional refresh_token, and cannot start the device flow. The legacy /auth/device_authorization path remains a compatibility alias.
 
 ## Authorization
 
 ```yaml
-path: /auth/device_authorization
-runtimePath: /auth/device_authorization
+path: /auth/device-authorization
+runtimePath: /auth/device-authorization
 method: POST
 operationId: deviceAuthorize
 security:
@@ -27,7 +27,7 @@ resourcePermissionRequired: false
 ## Complete operation contract
 
 ```yaml
-path: /auth/device_authorization
+path: /auth/device-authorization
 post:
   tags:
     - Auth
@@ -44,7 +44,8 @@ post:
 
     Uses the existing managed-client device flow. This endpoint is public, but validates its client
     and supported device grant; anonymous DCR clients support authorization_code and optional
-    refresh_token, and cannot start the device flow.
+    refresh_token, and cannot start the device flow. The legacy /auth/device_authorization path
+    remains a compatibility alias.
   operationId: deviceAuthorize
   security:
     - {}
@@ -54,6 +55,8 @@ post:
       application/x-www-form-urlencoded:
         schema:
           $ref: '#/components/schemas/DeviceAuthorizationRequest'
+        example:
+          client_id: dcr_example
   responses:
     '200':
       description: Device authorization initiated successfully
@@ -61,18 +64,30 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/DeviceAuthorizationResponse'
+          example:
+            device_code: port1/principals/example
+            user_code: port1/principals/example
+            verification_uri: https://portpowered.com/oauth/device/verify
+            expires_in: 1800
+            interval: 5
     '400':
       description: Invalid request parameters
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
     '500':
       description: Internal server error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
   x-portos-delegated: false
   x-portos-resource-permission: false
 ```

package/generated/public/docs/for-ai/operations/enumerateEndpoints.md

@@ -58,7 +58,7 @@ get:
         check-token:
           value: ~caller
         check-id:
-          value: port1/user/alice/user/alice
+          value: port1/principals/example
     - name: id
       in: query
       description: The unique identifier of a specific endpoint to retrieve
@@ -67,7 +67,7 @@ get:
         type: string
       examples:
         endpoint-id:
-          value: port1/user/alice/endpoints/abc-123
+          value: port1/principals/example/endpoints/light-1
     - name: type
       in: query
       description: Filter endpoints by their primary type
@@ -76,7 +76,7 @@ get:
         type: string
       examples:
         type-filter:
-          value: light
+          value: LIGHT
     - name: serialNumber
       in: query
       description: Filter endpoints by their serial number
@@ -94,7 +94,7 @@ get:
         type: string
       examples:
         next-token:
-          value: '123'
+          value: OPAQUE_TOKEN_FROM_PREVIOUS_RESPONSE
     - name: maxResults
       in: query
       description: The maximum number of results to return
@@ -145,6 +145,16 @@ get:
           schema:
             $ref: '#/components/schemas/EndpointQueryResponse'
           examples: {}
+          example:
+            results:
+              - id: port1/principals/example/endpoints/light-1
+                name:
+                  type: PLAIN
+                  value: Office light
+                type: LIGHT
+                interfaces: []
+                ownerId: port1/principals/example
+                enablement: ENABLED
     '400':
       description: Bad request - missing required parameters
       content:

package/generated/public/docs/for-ai/operations/establishAuthLink.md

@@ -48,6 +48,8 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/EstablishAuthLinkRequest'
+        example:
+          pluginId: port1/principals/example
   responses:
     '200':
       description: Auth link established successfully

package/generated/public/docs/for-ai/operations/establishPlugin.md

@@ -49,6 +49,9 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/EstablishPluginRequest'
+        example:
+          plugin:
+            type: LIGHT
   responses:
     '200':
       description: Plugin established successfully
@@ -56,6 +59,8 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/EstablishPluginResponse'
+          example:
+            pluginId: port1/principals/example
     '400':
       description: Invalid request payload
       content:

package/generated/public/docs/for-ai/operations/evaluateAccessControlRule.md

@@ -44,6 +44,8 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/EvaluateAccessControlRuleRequest'
+        example:
+          requests: port1/principals/example
   responses:
     '200':
       description: Access control rule evaluated successfully

package/generated/public/docs/for-ai/operations/generateOAuthCode.md

@@ -51,6 +51,9 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/GenerateOAuthCodeRequest'
+        example:
+          client_id: port1/principals/user123/oauth-clients/my-client
+          redirect_uri: https://myapp.com/callback
   responses:
     '200':
       description: Authorization code generated successfully
@@ -58,6 +61,9 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/GenerateOAuthCodeResponse'
+          example:
+            code: abc123def456ghi789
+            expiryInSeconds: 600
     '400':
       description: Invalid request (e.g., invalid client_id, redirect_uri, or scopes)
     '401':

package/generated/public/docs/for-ai/operations/generateToken.md

@@ -52,7 +52,7 @@ post:
           redirect_uri: http://127.0.0.1:8765/callback
           code: CALLBACK_CODE
           code_verifier: ORIGINAL_RANDOM_PKCE_VERIFIER
-          resource: https://api.portpowered.com
+          resource: https://portos-pilot-api-685761720421.us-west1.run.app
   responses:
     '200':
       description: Token generated successfully

package/generated/public/docs/for-ai/operations/generateTuyaQrCode.md

@@ -57,6 +57,9 @@ post:
               description: >
                 Optional override for the Tuya authentication API endpoint. Defaults to
                 https://apigw.iotbing.com if not provided.
+        example:
+          accessCode: port1/principals/example
+          clientId: port1/principals/example
   responses:
     '200':
       description: QR code generated successfully

package/generated/public/docs/for-ai/operations/getAccessControlRules.md

@@ -89,6 +89,8 @@ get:
         application/json:
           schema:
             $ref: '#/components/schemas/GetAccessControlRulesResponse'
+          example:
+            results: []
     '500':
       description: Internal server error
       content:

package/generated/public/docs/for-ai/operations/getEndpointGroup.md

@@ -104,6 +104,14 @@ get:
         application/json:
           schema:
             $ref: '#/components/schemas/EndpointGroup'
+          example:
+            id: port1/principals/example/endpoint-groups/living-room
+            name:
+              type: LIGHT
+              value: port1/principals/example
+            ownerId: port1/principals/example
+            interfaces: []
+            etag: '"12"'
     '400':
       description: Invalid request payload
       content:

package/generated/public/docs/for-ai/operations/getOAuthAuthorizationServerMetadata.md

@@ -45,7 +45,6 @@ get:
               - issuer
               - authorization_endpoint
               - token_endpoint
-              - registration_endpoint
               - revocation_endpoint
               - scopes_supported
             properties:
@@ -61,6 +60,7 @@ get:
               registration_endpoint:
                 type: string
                 format: uri
+                description: Advertised when new anonymous registration is enabled; omitted when disabled.
               revocation_endpoint:
                 type: string
                 format: uri
@@ -85,6 +85,24 @@ get:
                 type: boolean
               authorization_response_iss_parameter_supported:
                 type: boolean
+          example:
+            issuer: https://portos-pilot-api-685761720421.us-west1.run.app
+            authorization_endpoint: https://portos-pilot-api-685761720421.us-west1.run.app/oauth/authorize
+            token_endpoint: https://portos-pilot-api-685761720421.us-west1.run.app/auth/token
+            revocation_endpoint: https://portos-pilot-api-685761720421.us-west1.run.app/auth/revoke
+            scopes_supported:
+              - endpoint:read
+              - message:send
+            registration_endpoint: https://portos-pilot-api-685761720421.us-west1.run.app/oauth/register
+            jwks_uri: https://portos-pilot-api-685761720421.us-west1.run.app/.well-known/jwks.json
+            code_challenge_methods_supported:
+              - S256
+            token_endpoint_auth_methods_supported:
+              - none
+              - client_secret_post
+              - client_secret_basic
+            client_id_metadata_document_supported: true
+            authorization_response_iss_parameter_supported: true
 ```
 
 Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getOAuthClient.md

@@ -76,6 +76,9 @@ get:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthClient'
+          example:
+            clientId: port1/systems/zero/oauth-clients/1234567890
+            clientName: port1/principals/example
     '400':
       description: Invalid request payload
       content:

package/generated/public/docs/for-ai/operations/getOpenIDConfiguration.md

@@ -81,7 +81,18 @@ get:
                   - urn:ietf:params:oauth:grant-type:token-exchange
                   - urn:ietf:params:oauth:grant-type:device_code
           example:
-            key: value
+            issuer: https://portos-pilot-api-685761720421.us-west1.run.app
+            jwks_uri: https://portos-pilot-api-685761720421.us-west1.run.app/.well-known/jwks.json
+            token_endpoint: https://portos-pilot-api-685761720421.us-west1.run.app/auth/token
+            response_types_supported:
+              - code
+            subject_types_supported:
+              - public
+            id_token_signing_alg_values_supported:
+              - RS256
+            grant_types_supported:
+              - authorization_code
+              - refresh_token
   x-portos-delegated: false
   x-portos-resource-permission: false
 ```

package/generated/public/docs/for-ai/operations/getPendingOAuthConsent.md

@@ -73,6 +73,12 @@ get:
                 type: array
                 items:
                   type: string
+          example:
+            client_id: dcr_example
+            client_name: Example agent
+            redirect_uri: http://127.0.0.1:8765/callback
+            resource: https://portos-pilot-api-685761720421.us-west1.run.app
+            scopes: []
     '400':
       description: Invalid, expired or consumed request.
     '401':

package/generated/public/docs/for-ai/operations/getView.md

@@ -84,6 +84,8 @@ get:
         application/json:
           schema:
             $ref: '#/components/schemas/View'
+          example:
+            id: port1/principals/example
     '400':
       description: Invalid request payload
       content:

package/generated/public/docs/for-ai/operations/handleGoogleCloudSchedulerWebhook.md

@@ -70,6 +70,9 @@ post:
             node_id:
               type: string
               description: The Port OS identifier of the flow node to execute
+        example:
+          flow_id: port1/principals/example
+          node_id: port1/principals/example
   responses:
     '200':
       description: Webhook received and flow run triggered (always returned to prevent retries)

package/generated/public/docs/for-ai/operations/handleOAuthCallback.md

@@ -62,12 +62,19 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/GenerateTokenResponse'
+          example:
+            access_token: port1/principals/example
+            token_type: port1/principals/example
+            expires_in: 1
     '400':
       description: Invalid callback data or provider error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
   x-portos-delegated: false
   x-portos-resource-permission: false
 ```

package/generated/public/docs/for-ai/operations/index.md

@@ -68,7 +68,7 @@ Use the operation’s scopes and its resource permission requirements. Public di
 - [DELETE /{namespace}/{principalType}/{principalId}/tokens/{tokenId}](/docs/for-ai/operations/invalidateToken.md)
 - [POST /auth/raise](/docs/for-ai/operations/raiseAnonymousPrincipal.md)
 - [POST /auth/callback](/docs/for-ai/operations/handleOAuthCallback.md)
-- [POST /auth/device_authorization](/docs/for-ai/operations/deviceAuthorize.md)
+- [POST /auth/device-authorization](/docs/for-ai/operations/deviceAuthorize.md)
 - [GET /oauth-clients](/docs/for-ai/operations/enumerateOAuthClients.md)
 - [POST /oauth-clients](/docs/for-ai/operations/createOAuthClient.md)
 - [GET /port1/{principalType}/{principalId}/oauth-clients/{clientId}](/docs/for-ai/operations/getOAuthClient.md)

package/generated/public/docs/for-ai/operations/invalidateToken.md

@@ -73,6 +73,8 @@ delete:
         application/json:
           schema:
             $ref: '#/components/schemas/InvalidateTokenResponse'
+          example:
+            message: The request could not be completed. Check the supplied parameters and try again.
     '401':
       description: Unauthorized
     '403':

package/generated/public/docs/for-ai/operations/pluginAuthCodeExchange.md

@@ -43,6 +43,10 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/PluginAuthCodeExchangeRequest'
+        example:
+          pluginId: port1/principals/example
+          principalId: port1/principals/example
+          pluginAuthenticationData: {}
   responses:
     '202':
       description: Plugin auth code exchange started successfully, the operation is ongoing in the background.

package/generated/public/docs/for-ai/operations/pluginAuthMultifactorExchange.md

@@ -44,6 +44,10 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/PluginAuthMultifactorExchangeRequest'
+        example:
+          pluginId: port1/principals/example
+          principalId: port1/principals/example
+          pluginAuthenticationData: {}
   responses:
     '202':
       description: Auth link setup started successfully, the operation is ongoing in the background.

package/generated/public/docs/for-ai/operations/pushToMessageGateway.md

@@ -42,6 +42,8 @@ post:
       application/json:
         schema:
           $ref: '#/components/schemas/Message'
+        example:
+          body: {}
   responses:
     '202':
       description: Message accepted for processing

package/generated/public/docs/for-ai/operations/raiseAnonymousPrincipal.md

@@ -55,6 +55,10 @@ post:
               type: string
               description: |
                 Token type identifier. Must be urn:ietf:params:oauth:token-type:id_token
+        example:
+          anonymous_refresh_token: port1/principals/example
+          subject_token: port1/principals/example
+          subject_token_type: port1/principals/example
   responses:
     '200':
       description: Principal raised successfully
@@ -62,24 +66,37 @@ post:
         application/json:
           schema:
             $ref: '#/components/schemas/GenerateTokenResponse'
+          example:
+            access_token: port1/principals/example
+            token_type: port1/principals/example
+            expires_in: 1
     '400':
       description: Invalid request (malformed form data or invalid parameters)
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
     '401':
       description: Invalid grant (anonymous refresh token is not valid)
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
     '500':
       description: Internal server error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/OAuthErrorResponse'
+          example:
+            error: invalid_request
+            error_description: user_code is required
   x-portos-delegated: false
   x-portos-resource-permission: false
 ```

package/generated/public/docs/for-ai/operations/refreshAuthLinkToken.md

@@ -54,6 +54,8 @@ post:
             authLinkId:
               type: string
               description: The ID of the auth link to refresh tokens for
+        example:
+          authLinkId: port1/principals/example
   responses:
     '200':
       description: Token refreshed successfully