changedInput schema / properties / operations / items / oneOf
Previous value: -[
- {
- "additionalProperties": false,
- "description": "Creates a user group. Its new ID and etag are returned in the result; later operations in the same batch cannot reference it. A user group name is `{\"type\": \"PLAIN\", \"value\": ...}` whose value is non-blank UTF-8 text of at most 256 bytes with no control characters; anything else is rejected with BAD_REQUEST. Each added member must be the ID of an existing endpoint the caller can read; a malformed ID is BAD_REQUEST, and a missing or unreadable endpoint is NOT_FOUND.\n",
- "properties": {
- "memberEndpointIds": {
- "description": "Endpoint IDs.",
- "items": {
- "minLength": 1,
- "type": "string"
- },
- "maxItems": 100,
- "minItems": 1,
- "type": "array",
- "uniqueItems": true
- },
- "name": {
- "properties": {
- "type": {
- "description": "The type identifier of the name value, defined as plain when not defined.",
- "type": "string"
- },
- "value": {
- "description": "the raw value of a plain name.",
- "type": "string"
- }
- },
- "required": [
- "type",
- "value"
- ],
- "type": "object"
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "CREATE_GROUP"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy; defaults to BEST_EFFORT."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Deletes a group.",
- "properties": {
- "etag": {
- "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group to modify.",
- "minLength": 1,
- "type": "string"
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "DELETE_GROUP"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy; defaults to BEST_EFFORT."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "groupId",
- "etag"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Renames a group. The name is a user override that survives rediscovery. A user group name is `{\"type\": \"PLAIN\", \"value\": ...}` whose value is non-blank UTF-8 text of at most 256 bytes with no control characters; anything else is rejected with BAD_REQUEST.\n",
- "properties": {
- "etag": {
- "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group to modify.",
- "minLength": 1,
- "type": "string"
- },
- "name": {
- "properties": {
- "type": {
- "description": "The type identifier of the name value, defined as plain when not defined.",
- "type": "string"
- },
- "value": {
- "description": "the raw value of a plain name.",
- "type": "string"
- }
- },
- "required": [
- "type",
- "value"
- ],
- "type": "object"
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "SET_NAME"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy; defaults to BEST_EFFORT."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "groupId",
- "etag",
- "name"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Adds endpoint members to a group. Each added member must be the ID of an existing endpoint the caller can read; a malformed ID is BAD_REQUEST, and a missing or unreadable endpoint is NOT_FOUND.\n",
- "properties": {
- "etag": {
- "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group to modify.",
- "minLength": 1,
- "type": "string"
- },
- "memberEndpointIds": {
- "description": "Endpoint IDs.",
- "items": {
- "minLength": 1,
- "type": "string"
- },
- "maxItems": 100,
- "minItems": 1,
- "type": "array",
- "uniqueItems": true
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "ADD_MEMBERS"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy; defaults to BEST_EFFORT."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "groupId",
- "etag",
- "memberEndpointIds"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Removes endpoint members from a group. IDs that are not members are ignored.\n",
- "properties": {
- "etag": {
- "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group to modify.",
- "minLength": 1,
- "type": "string"
- },
- "memberEndpointIds": {
- "description": "Endpoint IDs.",
- "items": {
- "minLength": 1,
- "type": "string"
- },
- "maxItems": 100,
- "minItems": 1,
- "type": "array",
- "uniqueItems": true
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "REMOVE_MEMBERS"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy; defaults to BEST_EFFORT."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "groupId",
- "etag",
- "memberEndpointIds"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Merges source groups into a target group. Source group routes are rehomed to the target, memberships are unioned, and each source ID becomes a redirect to the target. Identity decision that requires explicit user confirmation.",
- "properties": {
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "MERGE_INTO"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "PORTOS_ONLY",
- "description": "Only PORTOS_ONLY is supported; another mode returns 422 PROVIDER_SYNC_UNSUPPORTED."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- },
- "sources": {
- "description": "Groups merged into the target; each must be distinct from the target and from each other.",
- "items": {
- "additionalProperties": false,
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- },
- "maxItems": 20,
- "minItems": 1,
- "type": "array"
- },
- "target": {
- "additionalProperties": false,
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- }
- },
- "required": [
- "requestId",
- "operation",
- "sources",
- "target"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Enables or disables a group. A disabled group is hidden from group lists by default and cannot be targeted by messages such as clean-room. Rediscovery never re-enables it, so disabling (not deleting) is how a user hides a discovered group, such as a robot's room, for good.\n",
- "properties": {
- "enablement": {
- "default": "ENABLED",
- "description": "Whether Port OS uses an endpoint or group. A disabled one is hidden from collections by default and cannot be sent device messages or targeted by them; exact authorized reads still return it. Rediscovery never changes it, so disabling is how a user hides a discovered device or room for good.\n",
- "enum": [
- "ENABLED",
- "DISABLED"
- ],
- "type": "string"
- },
- "etag": {
- "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group to modify.",
- "minLength": 1,
- "type": "string"
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "SET_ENABLEMENT"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "PORTOS_ONLY",
- "description": "Only PORTOS_ONLY is supported; another mode returns 422 PROVIDER_SYNC_UNSUPPORTED."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "groupId",
- "etag",
- "enablement"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Moves one endpoint between distinct groups. Both references use their starting etags, shared with every other reference to these groups in this batch. The caller must be authorized to remove the member from the source, add it to the target and read the endpoint. Provider removal precedes addition. An exclusive add that would displace another group requires this operation rather than an implicit move.",
- "properties": {
- "memberEndpointId": {
- "description": "The existing endpoint to move.",
- "minLength": 1,
- "type": "string"
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "MOVE_MEMBER"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy; defaults to BEST_EFFORT."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- },
- "source": {
- "additionalProperties": false,
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- },
- "target": {
- "additionalProperties": false,
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- }
- },
- "required": [
- "requestId",
- "operation",
- "memberEndpointId",
- "source",
- "target"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "Enables or disables one stored provider group route. Disabling retains its observations but removes its membership and interfaces from resolution. Enabling an orphan can create or attach a group. The associated group's starting etag is required when the route has a group. Only PORTOS_ONLY is supported; another mode returns 422 PROVIDER_SYNC_UNSUPPORTED.",
- "properties": {
- "enablement": {
- "default": "ENABLED",
- "description": "Whether Port OS uses an endpoint or group. A disabled one is hidden from collections by default and cannot be sent device messages or targeted by them; exact authorized reads still return it. Rediscovery never changes it, so disabling is how a user hides a discovered device or room for good.\n",
- "enum": [
- "ENABLED",
- "DISABLED"
- ],
- "type": "string"
- },
- "etag": {
- "description": "The associated group's starting etag; omit only for an orphaned route.",
- "minLength": 1,
- "type": "string"
- },
- "groupRouteId": {
- "description": "The Port OS group route ID.",
- "minLength": 1,
- "type": "string"
- },
- "operation": {
- "description": "Operation discriminator.",
- "enum": [
- "SET_GROUP_ROUTE_ENABLEMENT"
- ],
- "type": "string"
- },
- "providerSync": {
- "allOf": [
- {
- "default": "BEST_EFFORT",
- "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
- "enum": [
- "PORTOS_ONLY",
- "BEST_EFFORT",
- "FAIL_ON_PROVIDER_ERROR"
- ],
- "type": "string"
- }
- ],
- "default": "PORTOS_ONLY",
- "description": "Only PORTOS_ONLY is supported, and it is the default."
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "requestId",
- "operation",
- "groupRouteId",
- "enablement"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "description": "Creates a user group. Its new ID and etag are returned in the result; later operations in the same batch cannot reference it. A user group name is `{\"type\": \"PLAIN\", \"value\": ...}` whose value is non-blank UTF-8 text of at most 256 bytes with no control characters; anything else is rejected with BAD_REQUEST. Each added member must be the ID of an existing endpoint the caller can read; a malformed ID is BAD_REQUEST, and a missing or unreadable endpoint is NOT_FOUND.\n",
+ "properties": {
+ "memberEndpointIds": {
+ "description": "Endpoint IDs.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 100,
+ "minItems": 1,
+ "type": "array",
+ "uniqueItems": true
+ },
+ "name": {
+ "properties": {
+ "type": {
+ "description": "The type identifier of the name value, defined as plain when not defined.",
+ "type": "string"
+ },
+ "value": {
+ "description": "the raw value of a plain name.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "value"
+ ],
+ "type": "object"
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "CREATE_GROUP"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy; defaults to BEST_EFFORT."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "name"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Deletes a group.",
+ "properties": {
+ "etag": {
+ "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group to modify.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "DELETE_GROUP"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy; defaults to BEST_EFFORT."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Renames a group. The name is a user override that survives rediscovery. A user group name is `{\"type\": \"PLAIN\", \"value\": ...}` whose value is non-blank UTF-8 text of at most 256 bytes with no control characters; anything else is rejected with BAD_REQUEST.\n",
+ "properties": {
+ "etag": {
+ "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group to modify.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "name": {
+ "properties": {
+ "type": {
+ "description": "The type identifier of the name value, defined as plain when not defined.",
+ "type": "string"
+ },
+ "value": {
+ "description": "the raw value of a plain name.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "value"
+ ],
+ "type": "object"
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "SET_NAME"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy; defaults to BEST_EFFORT."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "groupId",
+ "etag",
+ "name"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Adds endpoint members to a group. Each added member must be the ID of an existing endpoint the caller can read; a malformed ID is BAD_REQUEST, and a missing or unreadable endpoint is NOT_FOUND.\n",
+ "properties": {
+ "etag": {
+ "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group to modify.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "memberEndpointIds": {
+ "description": "Endpoint IDs.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 100,
+ "minItems": 1,
+ "type": "array",
+ "uniqueItems": true
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "ADD_MEMBERS"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy; defaults to BEST_EFFORT."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "groupId",
+ "etag",
+ "memberEndpointIds"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Removes endpoint members from a group. IDs that are not members are ignored.\n",
+ "properties": {
+ "etag": {
+ "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group to modify.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "memberEndpointIds": {
+ "description": "Endpoint IDs.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 100,
+ "minItems": 1,
+ "type": "array",
+ "uniqueItems": true
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "REMOVE_MEMBERS"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy; defaults to BEST_EFFORT."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "groupId",
+ "etag",
+ "memberEndpointIds"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Merges source groups into a target group. Source group routes are rehomed to the target, memberships are unioned, and each source ID becomes a redirect to the target. Identity decision that requires explicit user confirmation.",
+ "properties": {
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "MERGE_INTO"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "PORTOS_ONLY",
+ "description": "Only PORTOS_ONLY is supported; another mode returns 422 PROVIDER_SYNC_UNSUPPORTED."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "sources": {
+ "description": "Groups merged into the target; each must be distinct from the target and from each other.",
+ "items": {
+ "additionalProperties": false,
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ },
+ "maxItems": 20,
+ "minItems": 1,
+ "type": "array"
+ },
+ "target": {
+ "additionalProperties": false,
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "sources",
+ "target"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Enables or disables a group. A disabled group is hidden from group lists by default and cannot be targeted by messages such as clean-room. Rediscovery never re-enables it, so disabling (not deleting) is how a user hides a discovered group, such as a robot's room, for good.\n",
+ "properties": {
+ "enablement": {
+ "default": "ENABLED",
+ "description": "Whether Port OS uses an endpoint or group. A disabled one is hidden from collections by default and cannot be sent device messages or targeted by them; exact authorized reads still return it. Rediscovery never changes it, so disabling is how a user hides a discovered device or room for good.\n",
+ "enum": [
+ "ENABLED",
+ "DISABLED"
+ ],
+ "type": "string"
+ },
+ "etag": {
+ "description": "The group starting etag the client last read, shared by all references in this batch. A meaningful change advances the group once at final commit; results use its final etag.\n",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group to modify.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "SET_ENABLEMENT"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "PORTOS_ONLY",
+ "description": "Only PORTOS_ONLY is supported; another mode returns 422 PROVIDER_SYNC_UNSUPPORTED."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "groupId",
+ "etag",
+ "enablement"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Moves one endpoint between distinct groups. Both references use their starting etags, shared with every other reference to these groups in this batch. The caller must be authorized to remove the member from the source, add it to the target and read the endpoint. Provider removal precedes addition. An exclusive add that would displace another group requires this operation rather than an implicit move.",
+ "properties": {
+ "memberEndpointId": {
+ "description": "The existing endpoint to move.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "MOVE_MEMBER"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy; defaults to BEST_EFFORT."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "source": {
+ "additionalProperties": false,
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "additionalProperties": false,
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "memberEndpointId",
+ "source",
+ "target"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "Enables or disables one stored provider group route. Disabling retains its observations but removes its membership and interfaces from resolution. Enabling an orphan can create or attach a group. The route starting etag is always required. groupEtag is required when the route has an associated group. Only PORTOS_ONLY is supported; another mode returns 422 PROVIDER_SYNC_UNSUPPORTED.",
+ "properties": {
+ "enablement": {
+ "default": "ENABLED",
+ "description": "Whether Port OS uses an endpoint or group. A disabled one is hidden from collections by default and cannot be sent device messages or targeted by them; exact authorized reads still return it. Rediscovery never changes it, so disabling is how a user hides a discovered device or room for good.\n",
+ "enum": [
+ "ENABLED",
+ "DISABLED"
+ ],
+ "type": "string"
+ },
+ "etag": {
+ "description": "The native route's starting etag from a group-route read.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupEtag": {
+ "description": "The associated group's starting etag; required when the route has a group.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupRouteId": {
+ "description": "The Port OS group route ID.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "operation": {
+ "description": "Operation discriminator.",
+ "enum": [
+ "SET_GROUP_ROUTE_ENABLEMENT"
+ ],
+ "type": "string"
+ },
+ "providerSync": {
+ "allOf": [
+ {
+ "default": "BEST_EFFORT",
+ "description": "Provider synchronization policy. BEST_EFFORT asks declared providers first and saves local fallback intent on failure. FAIL_ON_PROVIDER_ERROR fails the customer batch on a failed supported dispatch while retaining received provider truth. PORTOS_ONLY changes local intent. Undeclared messages are reported as NOT_SUPPORTED and do not prevent local changes.",
+ "enum": [
+ "PORTOS_ONLY",
+ "BEST_EFFORT",
+ "FAIL_ON_PROVIDER_ERROR"
+ ],
+ "type": "string"
+ }
+ ],
+ "default": "PORTOS_ONLY",
+ "description": "Only PORTOS_ONLY is supported, and it is the default."
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "groupRouteId",
+ "etag",
+ "enablement"
+ ],
+ "type": "object"
+ }
+]
changedOutput schema / oneOf
Previous value: -[
- {
- "additionalProperties": false,
- "description": "Evaluated batch envelope. COMMITTED and PARTIALLY_SUCCEEDED save all customer operations; PARTIALLY_SUCCEEDED includes at least one PARTIALLY_APPLIED fallback. FAILED saves no rejected customer intent, but retains valid provider truth and the terminal failed receipt after any provider attempt. Failed results list attempted operations as NOT_APPLIED without group etags; errors contains one item per failing operation. Items correlate by requestId, never position.",
- "properties": {
- "errors": {
- "items": {
- "description": "Error for one operation of an atomic batch, correlated by the operation's `requestId`. `status` is the HTTP status the operation would have returned on its own.\n",
- "properties": {
- "code": {
- "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
- "enum": [
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "INSUFFICIENT_SCOPE",
- "NOT_FOUND",
- "CONFLICT",
- "UNPROCESSABLE_ENTITY",
- "UNSUPPORTED_OPERATION",
- "TOO_MANY_REQUESTS",
- "SERVICE_UNAVAILABLE",
- "NOT_IMPLEMENTED",
- "INTERNAL",
- "CHECKSUM_MISMATCH",
- "FILE_TOO_LARGE",
- "STORAGE_UNAVAILABLE",
- "INSUFFICIENT_PERMISSIONS",
- "INVALID_FILE_TYPE",
- "QUOTA_EXCEEDED",
- "CONCURRENT_MODIFICATION",
- "ENDPOINT_UNREACHABLE",
- "BRIDGE_UNREACHABLE",
- "CLOUD_CONTROL_DISABLED",
- "ENDPOINT_BUSY",
- "ENDPOINT_LOW_POWER",
- "AUTHORIZATION_CREDENTIAL_INVALID",
- "AUTHORIZATION_CREDENTIAL_EXPIRED",
- "INVALID_DIRECTIVE",
- "INVALID_VALUE",
- "VALUE_OUT_OF_RANGE",
- "NOT_SUPPORTED_IN_CURRENT_MODE",
- "RATE_LIMIT_EXCEEDED",
- "PROVIDER_SERVICE_UNAVAILABLE",
- "PROVIDER_TIMEOUT",
- "PROVIDER_INTERNAL_ERROR",
- "INVALID_PROVIDER_RESPONSE",
- "OUTCOME_UNKNOWN",
- "PRECONDITION_FAILED",
- "AUTH_LINK_NOT_READY",
- "AUTH_LINK_NOT_DISCONNECTABLE",
- "PRECONDITION_REQUIRED",
- "IDEMPOTENCY_KEY_REQUIRED",
- "IDEMPOTENCY_KEY_REUSED",
- "IDEMPOTENCY_KEY_IN_FLIGHT",
- "IDEMPOTENCY_KEY_INVALID",
- "GROUP_MERGED",
- "MULTI_ROOM_UNSUPPORTED",
- "MAP_NOT_ACTIVE",
- "TARGET_UNSUPPORTED",
- "TARGET_AMBIGUOUS",
- "TARGET_GROUP_NOT_FOUND",
- "TARGET_GROUP_DISABLED",
- "DUPLICATE_TARGET_GROUP",
- "MESSAGE_UNSUPPORTED",
- "MESSAGE_AMBIGUOUS",
- "ENDPOINT_DISABLED",
- "ENDPOINT_ROUTE_CHANGED",
- "ENDPOINT_HAS_DEPENDENCIES",
- "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
- "ENDPOINT_COMMITTED_CLEANUP_PENDING",
- "DEEP_QUERY_FAILED",
- "PROVIDER_NO_STATE",
- "EVENT_MANAGEMENT_DISABLED",
- "SUBSCRIPTION_IDENTITY_IMMUTABLE",
- "UNSUPPORTED_MEDIA_TYPE",
- "EVENT_PAYLOAD_TOO_LARGE",
- "REQUEST_BODY_TOO_LARGE",
- "EVENT_IDENTITY_CONFLICT",
- "EVENT_INGRESS_QUOTA_EXCEEDED",
- "EVENT_RECEIPT_EXPIRED",
- "EVENT_STORAGE_UNAVAILABLE",
- "EVENT_DEAD_LETTER_NOT_FOUND",
- "EVENT_REDRIVE_CONFLICT",
- "EVENT_REDRIVE_EXPIRED",
- "RECEIPT_CONTEXT_EXPIRED",
- "EVENT_MAINTENANCE_INCOMPLETE",
- "UNKNOWN_INTERFACE",
- "INVALID_CONFIGURATION",
- "INVALID_PLUGIN_MANIFEST",
- "INVALID_ATTRIBUTE",
- "INVALID_PROVIDER_MESSAGE",
- "UNDECLARED_CAPABILITY",
- "PLUGIN_ROUTE_ID_CONFLICT",
- "UNRESOLVED_REFERENCE",
- "INVALID_RELATIONSHIP",
- "RELATIONSHIP_CYCLE",
- "MULTIPLE_PARENTS",
- "FLOW_VALIDATION_FAILED",
- "PROVIDER_SYNC_UNSUPPORTED"
- ],
- "type": "string"
- },
- "family": {
- "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
- "enum": [
- "NOT_FOUND",
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "CONFLICT",
- "GONE",
- "PRECONDITION_FAILED",
- "PRECONDITION_REQUIRED",
- "PAYLOAD_TOO_LARGE",
- "UNSUPPORTED_MEDIA_TYPE",
- "UNPROCESSABLE_ENTITY",
- "LOCKED",
- "TOO_MANY_REQUESTS",
- "BAD_GATEWAY",
- "SERVICE_UNAVAILABLE",
- "GATEWAY_TIMEOUT",
- "NOT_IMPLEMENTED",
- "INTERNAL_SERVER_ERROR",
- "REQUEST_INVALID",
- "AUTHENTICATION",
- "PERMISSION",
- "ENDPOINT_NOT_FOUND",
- "ENDPOINT_STATE_CONFLICT",
- "ENDPOINT_UNAVAILABLE",
- "RATE_LIMIT",
- "PROVIDER_BAD_RESPONSE",
- "PROVIDER_UNAVAILABLE",
- "PROVIDER_TIMEOUT"
- ],
- "type": "string"
- },
- "message": {
- "description": "Plain-language description of the failure and the suggested next action.",
- "type": "string"
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- },
- "resourceId": {
- "description": "The resource the failure applies to, when it is not the operation's primary target.",
- "type": "string"
- },
- "status": {
- "description": "HTTP-equivalent status code of the item failure.",
- "maximum": 599,
- "minimum": 400,
- "type": "integer"
- }
- },
- "required": [
- "requestId",
- "code",
- "family",
- "status",
- "message"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "results": {
- "items": {
- "description": "One operation outcome correlated by requestId. Applied results use final committed group etags; MOVE_MEMBER returns source and target. NOT_APPLIED reports attempted provider dispatches from a failed customer batch without group, source or target etags. Dispatch errors remain attached to their entries. Operations that reached no provider are omitted from failed batch results.",
- "properties": {
- "deletedGroupId": {
- "description": "The deleted group ID (`DELETE_GROUP`).",
- "type": "string"
- },
- "group": {
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- },
- "operation": {
- "description": "Discriminator of an endpoint group management operation.",
- "enum": [
- "CREATE_GROUP",
- "DELETE_GROUP",
- "SET_NAME",
- "ADD_MEMBERS",
- "REMOVE_MEMBERS",
- "MERGE_INTO",
- "SET_ENABLEMENT",
- "MOVE_MEMBER",
- "SET_GROUP_ROUTE_ENABLEMENT"
- ],
- "type": "string"
- },
- "providerDispatches": {
- "description": "This operation's provider messages; an empty array is explicit.",
- "items": {
- "description": "One provider message for this operation. SUCCEEDED requires a valid read-back reply establishing the requested condition. Provider identities are present only with the same native-route or account read visibility required by the public query projection. An authorized write can still return a redacted dispatch outcome; its namespace, name, status, reason and error code remain. Errors for hidden metadata use a generic message and omit details.",
- "properties": {
- "authLinkId": {
- "description": "The provider account authorization link ID; omitted without metadata read visibility, empty for a readable account without a link.",
- "type": "string"
- },
- "error": {
- "description": "The one Port OS error shape, returned by every REST error response and every MCP tool error. `code` names the specific failure and `family` its broad class; both are closed enums, so clients branch on them and show `message`, which says what failed and what to do next.",
- "properties": {
- "code": {
- "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
- "enum": [
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "INSUFFICIENT_SCOPE",
- "NOT_FOUND",
- "CONFLICT",
- "UNPROCESSABLE_ENTITY",
- "UNSUPPORTED_OPERATION",
- "TOO_MANY_REQUESTS",
- "SERVICE_UNAVAILABLE",
- "NOT_IMPLEMENTED",
- "INTERNAL",
- "CHECKSUM_MISMATCH",
- "FILE_TOO_LARGE",
- "STORAGE_UNAVAILABLE",
- "INSUFFICIENT_PERMISSIONS",
- "INVALID_FILE_TYPE",
- "QUOTA_EXCEEDED",
- "CONCURRENT_MODIFICATION",
- "ENDPOINT_UNREACHABLE",
- "BRIDGE_UNREACHABLE",
- "CLOUD_CONTROL_DISABLED",
- "ENDPOINT_BUSY",
- "ENDPOINT_LOW_POWER",
- "AUTHORIZATION_CREDENTIAL_INVALID",
- "AUTHORIZATION_CREDENTIAL_EXPIRED",
- "INVALID_DIRECTIVE",
- "INVALID_VALUE",
- "VALUE_OUT_OF_RANGE",
- "NOT_SUPPORTED_IN_CURRENT_MODE",
- "RATE_LIMIT_EXCEEDED",
- "PROVIDER_SERVICE_UNAVAILABLE",
- "PROVIDER_TIMEOUT",
- "PROVIDER_INTERNAL_ERROR",
- "INVALID_PROVIDER_RESPONSE",
- "OUTCOME_UNKNOWN",
- "PRECONDITION_FAILED",
- "AUTH_LINK_NOT_READY",
- "AUTH_LINK_NOT_DISCONNECTABLE",
- "PRECONDITION_REQUIRED",
- "IDEMPOTENCY_KEY_REQUIRED",
- "IDEMPOTENCY_KEY_REUSED",
- "IDEMPOTENCY_KEY_IN_FLIGHT",
- "IDEMPOTENCY_KEY_INVALID",
- "GROUP_MERGED",
- "MULTI_ROOM_UNSUPPORTED",
- "MAP_NOT_ACTIVE",
- "TARGET_UNSUPPORTED",
- "TARGET_AMBIGUOUS",
- "TARGET_GROUP_NOT_FOUND",
- "TARGET_GROUP_DISABLED",
- "DUPLICATE_TARGET_GROUP",
- "MESSAGE_UNSUPPORTED",
- "MESSAGE_AMBIGUOUS",
- "ENDPOINT_DISABLED",
- "ENDPOINT_ROUTE_CHANGED",
- "ENDPOINT_HAS_DEPENDENCIES",
- "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
- "ENDPOINT_COMMITTED_CLEANUP_PENDING",
- "DEEP_QUERY_FAILED",
- "PROVIDER_NO_STATE",
- "EVENT_MANAGEMENT_DISABLED",
- "SUBSCRIPTION_IDENTITY_IMMUTABLE",
- "UNSUPPORTED_MEDIA_TYPE",
- "EVENT_PAYLOAD_TOO_LARGE",
- "REQUEST_BODY_TOO_LARGE",
- "EVENT_IDENTITY_CONFLICT",
- "EVENT_INGRESS_QUOTA_EXCEEDED",
- "EVENT_RECEIPT_EXPIRED",
- "EVENT_STORAGE_UNAVAILABLE",
- "EVENT_DEAD_LETTER_NOT_FOUND",
- "EVENT_REDRIVE_CONFLICT",
- "EVENT_REDRIVE_EXPIRED",
- "RECEIPT_CONTEXT_EXPIRED",
- "EVENT_MAINTENANCE_INCOMPLETE",
- "UNKNOWN_INTERFACE",
- "INVALID_CONFIGURATION",
- "INVALID_PLUGIN_MANIFEST",
- "INVALID_ATTRIBUTE",
- "INVALID_PROVIDER_MESSAGE",
- "UNDECLARED_CAPABILITY",
- "PLUGIN_ROUTE_ID_CONFLICT",
- "UNRESOLVED_REFERENCE",
- "INVALID_RELATIONSHIP",
- "RELATIONSHIP_CYCLE",
- "MULTIPLE_PARENTS",
- "FLOW_VALIDATION_FAILED",
- "PROVIDER_SYNC_UNSUPPORTED"
- ],
- "type": "string"
- },
- "details": {
- "description": "Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.\n",
- "properties": {
- "actual": {
- "description": "String representation of the submitted value when the plugin can safely report it.",
- "type": "string"
- },
- "correlationId": {
- "description": "Provider or plugin correlation ID useful for support.",
- "type": "string"
- },
- "correlationToken": {
- "description": "Token that correlates an outcome-unknown dispatch with its eventual result.",
- "type": "string"
- },
- "currentMode": {
- "description": "Current endpoint mode when `code` is `NOT_SUPPORTED_IN_CURRENT_MODE`.",
- "type": "string"
- },
- "directive": {
- "description": "Message namespace and name or provider directive that failed.",
- "type": "string"
- },
- "discoveryEndpointId": {
- "description": "Port OS provider endpoint (type ENDPOINT_PLUGIN) of the connection to send `discover-routes` to when `code` is `TARGET_UNSUPPORTED` because the route must be rediscovered.",
- "type": "string"
- },
- "endpointId": {
- "description": "Port OS endpoint ID involved in the failed dispatch.",
- "type": "string"
- },
- "fieldErrors": {
- "description": "The request fields that were rejected, when the error is about the request's content.",
- "items": {
- "description": "One rejected request field of an error.",
- "properties": {
- "field": {
- "description": "Name or JSON path of the rejected field.",
- "type": "string"
- },
- "reason": {
- "description": "Why the field was rejected and what an accepted value looks like.",
- "type": "string"
- }
- },
- "required": [
- "field",
- "reason"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "maximum": {
- "description": "Maximum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
- "type": "number"
- },
- "minimum": {
- "description": "Minimum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
- "type": "number"
- },
- "parameter": {
- "description": "Request parameter or capability value that caused the failure.",
- "type": "string"
- },
- "pluginId": {
- "description": "Port OS plugin ID that reported the failure.",
- "type": "string"
- },
- "pluginRouteId": {
- "description": "Plugin-owned route identifier involved in the failed dispatch.",
- "type": "string"
- },
- "provider": {
- "description": "Third-party provider or bridge name that reported the failure.",
- "type": "string"
- },
- "providerCode": {
- "description": "The third-party provider's own error code, for support. It is opaque and provider-specific; branch on `code` and `family` instead.",
- "type": "string"
- },
- "retryAfterSeconds": {
- "description": "Suggested retry delay for rate-limit or provider-unavailable failures.",
- "minimum": 0,
- "type": "integer"
- }
- },
- "type": "object"
- },
- "errors": {
- "description": "Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.\n",
- "items": {
- "description": "One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.\n",
- "properties": {
- "code": {
- "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
- "enum": [
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "INSUFFICIENT_SCOPE",
- "NOT_FOUND",
- "CONFLICT",
- "UNPROCESSABLE_ENTITY",
- "UNSUPPORTED_OPERATION",
- "TOO_MANY_REQUESTS",
- "SERVICE_UNAVAILABLE",
- "NOT_IMPLEMENTED",
- "INTERNAL",
- "CHECKSUM_MISMATCH",
- "FILE_TOO_LARGE",
- "STORAGE_UNAVAILABLE",
- "INSUFFICIENT_PERMISSIONS",
- "INVALID_FILE_TYPE",
- "QUOTA_EXCEEDED",
- "CONCURRENT_MODIFICATION",
- "ENDPOINT_UNREACHABLE",
- "BRIDGE_UNREACHABLE",
- "CLOUD_CONTROL_DISABLED",
- "ENDPOINT_BUSY",
- "ENDPOINT_LOW_POWER",
- "AUTHORIZATION_CREDENTIAL_INVALID",
- "AUTHORIZATION_CREDENTIAL_EXPIRED",
- "INVALID_DIRECTIVE",
- "INVALID_VALUE",
- "VALUE_OUT_OF_RANGE",
- "NOT_SUPPORTED_IN_CURRENT_MODE",
- "RATE_LIMIT_EXCEEDED",
- "PROVIDER_SERVICE_UNAVAILABLE",
- "PROVIDER_TIMEOUT",
- "PROVIDER_INTERNAL_ERROR",
- "INVALID_PROVIDER_RESPONSE",
- "OUTCOME_UNKNOWN",
- "PRECONDITION_FAILED",
- "AUTH_LINK_NOT_READY",
- "AUTH_LINK_NOT_DISCONNECTABLE",
- "PRECONDITION_REQUIRED",
- "IDEMPOTENCY_KEY_REQUIRED",
- "IDEMPOTENCY_KEY_REUSED",
- "IDEMPOTENCY_KEY_IN_FLIGHT",
- "IDEMPOTENCY_KEY_INVALID",
- "GROUP_MERGED",
- "MULTI_ROOM_UNSUPPORTED",
- "MAP_NOT_ACTIVE",
- "TARGET_UNSUPPORTED",
- "TARGET_AMBIGUOUS",
- "TARGET_GROUP_NOT_FOUND",
- "TARGET_GROUP_DISABLED",
- "DUPLICATE_TARGET_GROUP",
- "MESSAGE_UNSUPPORTED",
- "MESSAGE_AMBIGUOUS",
- "ENDPOINT_DISABLED",
- "ENDPOINT_ROUTE_CHANGED",
- "ENDPOINT_HAS_DEPENDENCIES",
- "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
- "ENDPOINT_COMMITTED_CLEANUP_PENDING",
- "DEEP_QUERY_FAILED",
- "PROVIDER_NO_STATE",
- "EVENT_MANAGEMENT_DISABLED",
- "SUBSCRIPTION_IDENTITY_IMMUTABLE",
- "UNSUPPORTED_MEDIA_TYPE",
- "EVENT_PAYLOAD_TOO_LARGE",
- "REQUEST_BODY_TOO_LARGE",
- "EVENT_IDENTITY_CONFLICT",
- "EVENT_INGRESS_QUOTA_EXCEEDED",
- "EVENT_RECEIPT_EXPIRED",
- "EVENT_STORAGE_UNAVAILABLE",
- "EVENT_DEAD_LETTER_NOT_FOUND",
- "EVENT_REDRIVE_CONFLICT",
- "EVENT_REDRIVE_EXPIRED",
- "RECEIPT_CONTEXT_EXPIRED",
- "EVENT_MAINTENANCE_INCOMPLETE",
- "UNKNOWN_INTERFACE",
- "INVALID_CONFIGURATION",
- "INVALID_PLUGIN_MANIFEST",
- "INVALID_ATTRIBUTE",
- "INVALID_PROVIDER_MESSAGE",
- "UNDECLARED_CAPABILITY",
- "PLUGIN_ROUTE_ID_CONFLICT",
- "UNRESOLVED_REFERENCE",
- "INVALID_RELATIONSHIP",
- "RELATIONSHIP_CYCLE",
- "MULTIPLE_PARENTS",
- "FLOW_VALIDATION_FAILED",
- "PROVIDER_SYNC_UNSUPPORTED"
- ],
- "type": "string"
- },
- "family": {
- "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
- "enum": [
- "NOT_FOUND",
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "CONFLICT",
- "GONE",
- "PRECONDITION_FAILED",
- "PRECONDITION_REQUIRED",
- "PAYLOAD_TOO_LARGE",
- "UNSUPPORTED_MEDIA_TYPE",
- "UNPROCESSABLE_ENTITY",
- "LOCKED",
- "TOO_MANY_REQUESTS",
- "BAD_GATEWAY",
- "SERVICE_UNAVAILABLE",
- "GATEWAY_TIMEOUT",
- "NOT_IMPLEMENTED",
- "INTERNAL_SERVER_ERROR",
- "REQUEST_INVALID",
- "AUTHENTICATION",
- "PERMISSION",
- "ENDPOINT_NOT_FOUND",
- "ENDPOINT_STATE_CONFLICT",
- "ENDPOINT_UNAVAILABLE",
- "RATE_LIMIT",
- "PROVIDER_BAD_RESPONSE",
- "PROVIDER_UNAVAILABLE",
- "PROVIDER_TIMEOUT"
- ],
- "type": "string"
- },
- "interface": {
- "description": "Canonical capability interface name the failure applies to, when the failure is interface-specific.",
- "type": "string"
- },
- "message": {
- "description": "Plain-language description of the failure and the suggested fix.",
- "type": "string"
- },
- "pluginRouteId": {
- "description": "Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.",
- "type": "string"
- },
- "relationshipExternalId": {
- "description": "Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.",
- "type": "string"
- },
- "status": {
- "description": "HTTP-equivalent status code of the item failure.",
- "maximum": 599,
- "minimum": 400,
- "type": "integer"
- },
- "version": {
- "description": "Declared capability interface version the failure applies to, when the failure is interface-specific.",
- "type": "string"
- }
- },
- "required": [
- "code",
- "family",
- "status",
- "message"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "family": {
- "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
- "enum": [
- "NOT_FOUND",
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "CONFLICT",
- "GONE",
- "PRECONDITION_FAILED",
- "PRECONDITION_REQUIRED",
- "PAYLOAD_TOO_LARGE",
- "UNSUPPORTED_MEDIA_TYPE",
- "UNPROCESSABLE_ENTITY",
- "LOCKED",
- "TOO_MANY_REQUESTS",
- "BAD_GATEWAY",
- "SERVICE_UNAVAILABLE",
- "GATEWAY_TIMEOUT",
- "NOT_IMPLEMENTED",
- "INTERNAL_SERVER_ERROR",
- "REQUEST_INVALID",
- "AUTHENTICATION",
- "PERMISSION",
- "ENDPOINT_NOT_FOUND",
- "ENDPOINT_STATE_CONFLICT",
- "ENDPOINT_UNAVAILABLE",
- "RATE_LIMIT",
- "PROVIDER_BAD_RESPONSE",
- "PROVIDER_UNAVAILABLE",
- "PROVIDER_TIMEOUT"
- ],
- "type": "string"
- },
- "message": {
- "description": "Plain-language description of the failure and the suggested next action.",
- "type": "string"
- }
- },
- "required": [
- "family",
- "code",
- "message"
- ],
- "type": "object"
- },
- "groupRouteId": {
- "description": "The provider-native group route ID within this plugin and account, omitted without native-route read visibility.",
- "type": "string"
- },
- "impliedRemovals": {
- "description": "Authorized native memberships displaced by an explicit move.",
- "items": {
- "description": "In-scope membership removals implied by an exclusive provider move.",
- "properties": {
- "groupRouteId": {
- "description": "The Port OS group route affected by the removal.",
- "minLength": 1,
- "type": "string"
- },
- "memberEndpointIds": {
- "description": "Endpoint members removed from this route.",
- "items": {
- "minLength": 1,
- "type": "string"
- },
- "type": "array",
- "uniqueItems": true
- }
- },
- "required": [
- "groupRouteId",
- "memberEndpointIds"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "name": {
- "description": "The canonical message name.",
- "type": "string"
- },
- "namespace": {
- "description": "The message capability namespace.",
- "type": "string"
- },
- "pluginId": {
- "description": "The admitted provider plugin ID, omitted when provider metadata is not readable.",
- "type": "string"
- },
- "reason": {
- "description": "Why no provider dispatch was sent. NOT_DECLARED means the provider does not declare the message. OUTSIDE_PRINCIPAL means native mutations are limited to accounts owned by the original caller; sharing a group or endpoint does not grant native account-management authority. Local intent can still apply without dispatching to the foreign account.",
- "enum": [
- "NOT_DECLARED",
- "OUTSIDE_PRINCIPAL"
- ],
- "type": "string"
- },
- "status": {
- "description": "A planned, verified, failed or undeclared provider dispatch; a timeout is FAILED.",
- "enum": [
- "PLANNED",
- "SUCCEEDED",
- "FAILED",
- "NOT_SUPPORTED"
- ],
- "type": "string"
- }
- },
- "required": [
- "namespace",
- "name",
- "status"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "redirects": {
- "description": "Redirects written by `MERGE_INTO`.",
- "items": {
- "description": "A merged-away group ID and the group it now redirects to. Reads and control follow redirects; mutations fail with GROUP_MERGED.",
- "properties": {
- "from": {
- "description": "The merged-away group ID.",
- "type": "string"
- },
- "to": {
- "description": "The group it redirects to.",
- "type": "string"
- }
- },
- "required": [
- "from",
- "to"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "requestId": {
- "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
- "maxLength": 64,
- "minLength": 1,
- "type": "string"
- },
- "source": {
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- },
- "status": {
- "description": "APPLIED commits without a failed-dispatch fallback; PARTIALLY_APPLIED commits with one. NOT_APPLIED reports provider attempts from a failed customer batch and carries no group etag.",
- "enum": [
- "APPLIED",
- "PARTIALLY_APPLIED",
- "NOT_APPLIED"
- ],
- "type": "string"
- },
- "target": {
- "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
- "properties": {
- "etag": {
- "description": "The group's `etag` as last read by the client.",
- "minLength": 1,
- "type": "string"
- },
- "groupId": {
- "description": "The endpoint group ID.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "groupId",
- "etag"
- ],
- "type": "object"
- }
- },
- "required": [
- "requestId",
- "operation",
- "status",
- "providerDispatches"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "status": {
- "description": "COMMITTED means all customer operations applied. PARTIALLY_SUCCEEDED means they applied with a reported provider fallback. FAILED means customer intent did not commit; operation-specific contracts state whether already received provider observations are retained.",
- "enum": [
- "COMMITTED",
- "FAILED",
- "PARTIALLY_SUCCEEDED"
- ],
- "type": "string"
- }
- },
- "required": [
- "status",
- "results",
- "errors"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "description": "The one Port OS error shape, returned by every REST error response and every MCP tool error. `code` names the specific failure and `family` its broad class; both are closed enums, so clients branch on them and show `message`, which says what failed and what to do next.",
- "properties": {
- "code": {
- "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
- "enum": [
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "INSUFFICIENT_SCOPE",
- "NOT_FOUND",
- "CONFLICT",
- "UNPROCESSABLE_ENTITY",
- "UNSUPPORTED_OPERATION",
- "TOO_MANY_REQUESTS",
- "SERVICE_UNAVAILABLE",
- "NOT_IMPLEMENTED",
- "INTERNAL",
- "CHECKSUM_MISMATCH",
- "FILE_TOO_LARGE",
- "STORAGE_UNAVAILABLE",
- "INSUFFICIENT_PERMISSIONS",
- "INVALID_FILE_TYPE",
- "QUOTA_EXCEEDED",
- "CONCURRENT_MODIFICATION",
- "ENDPOINT_UNREACHABLE",
- "BRIDGE_UNREACHABLE",
- "CLOUD_CONTROL_DISABLED",
- "ENDPOINT_BUSY",
- "ENDPOINT_LOW_POWER",
- "AUTHORIZATION_CREDENTIAL_INVALID",
- "AUTHORIZATION_CREDENTIAL_EXPIRED",
- "INVALID_DIRECTIVE",
- "INVALID_VALUE",
- "VALUE_OUT_OF_RANGE",
- "NOT_SUPPORTED_IN_CURRENT_MODE",
- "RATE_LIMIT_EXCEEDED",
- "PROVIDER_SERVICE_UNAVAILABLE",
- "PROVIDER_TIMEOUT",
- "PROVIDER_INTERNAL_ERROR",
- "INVALID_PROVIDER_RESPONSE",
- "OUTCOME_UNKNOWN",
- "PRECONDITION_FAILED",
- "AUTH_LINK_NOT_READY",
- "AUTH_LINK_NOT_DISCONNECTABLE",
- "PRECONDITION_REQUIRED",
- "IDEMPOTENCY_KEY_REQUIRED",
- "IDEMPOTENCY_KEY_REUSED",
- "IDEMPOTENCY_KEY_IN_FLIGHT",
- "IDEMPOTENCY_KEY_INVALID",
- "GROUP_MERGED",
- "MULTI_ROOM_UNSUPPORTED",
- "MAP_NOT_ACTIVE",
- "TARGET_UNSUPPORTED",
- "TARGET_AMBIGUOUS",
- "TARGET_GROUP_NOT_FOUND",
- "TARGET_GROUP_DISABLED",
- "DUPLICATE_TARGET_GROUP",
- "MESSAGE_UNSUPPORTED",
- "MESSAGE_AMBIGUOUS",
- "ENDPOINT_DISABLED",
- "ENDPOINT_ROUTE_CHANGED",
- "ENDPOINT_HAS_DEPENDENCIES",
- "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
- "ENDPOINT_COMMITTED_CLEANUP_PENDING",
- "DEEP_QUERY_FAILED",
- "PROVIDER_NO_STATE",
- "EVENT_MANAGEMENT_DISABLED",
- "SUBSCRIPTION_IDENTITY_IMMUTABLE",
- "UNSUPPORTED_MEDIA_TYPE",
- "EVENT_PAYLOAD_TOO_LARGE",
- "REQUEST_BODY_TOO_LARGE",
- "EVENT_IDENTITY_CONFLICT",
- "EVENT_INGRESS_QUOTA_EXCEEDED",
- "EVENT_RECEIPT_EXPIRED",
- "EVENT_STORAGE_UNAVAILABLE",
- "EVENT_DEAD_LETTER_NOT_FOUND",
- "EVENT_REDRIVE_CONFLICT",
- "EVENT_REDRIVE_EXPIRED",
- "RECEIPT_CONTEXT_EXPIRED",
- "EVENT_MAINTENANCE_INCOMPLETE",
- "UNKNOWN_INTERFACE",
- "INVALID_CONFIGURATION",
- "INVALID_PLUGIN_MANIFEST",
- "INVALID_ATTRIBUTE",
- "INVALID_PROVIDER_MESSAGE",
- "UNDECLARED_CAPABILITY",
- "PLUGIN_ROUTE_ID_CONFLICT",
- "UNRESOLVED_REFERENCE",
- "INVALID_RELATIONSHIP",
- "RELATIONSHIP_CYCLE",
- "MULTIPLE_PARENTS",
- "FLOW_VALIDATION_FAILED",
- "PROVIDER_SYNC_UNSUPPORTED"
- ],
- "type": "string"
- },
- "details": {
- "description": "Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.\n",
- "properties": {
- "actual": {
- "description": "String representation of the submitted value when the plugin can safely report it.",
- "type": "string"
- },
- "correlationId": {
- "description": "Provider or plugin correlation ID useful for support.",
- "type": "string"
- },
- "correlationToken": {
- "description": "Token that correlates an outcome-unknown dispatch with its eventual result.",
- "type": "string"
- },
- "currentMode": {
- "description": "Current endpoint mode when `code` is `NOT_SUPPORTED_IN_CURRENT_MODE`.",
- "type": "string"
- },
- "directive": {
- "description": "Message namespace and name or provider directive that failed.",
- "type": "string"
- },
- "discoveryEndpointId": {
- "description": "Port OS provider endpoint (type ENDPOINT_PLUGIN) of the connection to send `discover-routes` to when `code` is `TARGET_UNSUPPORTED` because the route must be rediscovered.",
- "type": "string"
- },
- "endpointId": {
- "description": "Port OS endpoint ID involved in the failed dispatch.",
- "type": "string"
- },
- "fieldErrors": {
- "description": "The request fields that were rejected, when the error is about the request's content.",
- "items": {
- "description": "One rejected request field of an error.",
- "properties": {
- "field": {
- "description": "Name or JSON path of the rejected field.",
- "type": "string"
- },
- "reason": {
- "description": "Why the field was rejected and what an accepted value looks like.",
- "type": "string"
- }
- },
- "required": [
- "field",
- "reason"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "maximum": {
- "description": "Maximum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
- "type": "number"
- },
- "minimum": {
- "description": "Minimum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
- "type": "number"
- },
- "parameter": {
- "description": "Request parameter or capability value that caused the failure.",
- "type": "string"
- },
- "pluginId": {
- "description": "Port OS plugin ID that reported the failure.",
- "type": "string"
- },
- "pluginRouteId": {
- "description": "Plugin-owned route identifier involved in the failed dispatch.",
- "type": "string"
- },
- "provider": {
- "description": "Third-party provider or bridge name that reported the failure.",
- "type": "string"
- },
- "providerCode": {
- "description": "The third-party provider's own error code, for support. It is opaque and provider-specific; branch on `code` and `family` instead.",
- "type": "string"
- },
- "retryAfterSeconds": {
- "description": "Suggested retry delay for rate-limit or provider-unavailable failures.",
- "minimum": 0,
- "type": "integer"
- }
- },
- "type": "object"
- },
- "errors": {
- "description": "Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.\n",
- "items": {
- "description": "One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.\n",
- "properties": {
- "code": {
- "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
- "enum": [
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "INSUFFICIENT_SCOPE",
- "NOT_FOUND",
- "CONFLICT",
- "UNPROCESSABLE_ENTITY",
- "UNSUPPORTED_OPERATION",
- "TOO_MANY_REQUESTS",
- "SERVICE_UNAVAILABLE",
- "NOT_IMPLEMENTED",
- "INTERNAL",
- "CHECKSUM_MISMATCH",
- "FILE_TOO_LARGE",
- "STORAGE_UNAVAILABLE",
- "INSUFFICIENT_PERMISSIONS",
- "INVALID_FILE_TYPE",
- "QUOTA_EXCEEDED",
- "CONCURRENT_MODIFICATION",
- "ENDPOINT_UNREACHABLE",
- "BRIDGE_UNREACHABLE",
- "CLOUD_CONTROL_DISABLED",
- "ENDPOINT_BUSY",
- "ENDPOINT_LOW_POWER",
- "AUTHORIZATION_CREDENTIAL_INVALID",
- "AUTHORIZATION_CREDENTIAL_EXPIRED",
- "INVALID_DIRECTIVE",
- "INVALID_VALUE",
- "VALUE_OUT_OF_RANGE",
- "NOT_SUPPORTED_IN_CURRENT_MODE",
- "RATE_LIMIT_EXCEEDED",
- "PROVIDER_SERVICE_UNAVAILABLE",
- "PROVIDER_TIMEOUT",
- "PROVIDER_INTERNAL_ERROR",
- "INVALID_PROVIDER_RESPONSE",
- "OUTCOME_UNKNOWN",
- "PRECONDITION_FAILED",
- "AUTH_LINK_NOT_READY",
- "AUTH_LINK_NOT_DISCONNECTABLE",
- "PRECONDITION_REQUIRED",
- "IDEMPOTENCY_KEY_REQUIRED",
- "IDEMPOTENCY_KEY_REUSED",
- "IDEMPOTENCY_KEY_IN_FLIGHT",
- "IDEMPOTENCY_KEY_INVALID",
- "GROUP_MERGED",
- "MULTI_ROOM_UNSUPPORTED",
- "MAP_NOT_ACTIVE",
- "TARGET_UNSUPPORTED",
- "TARGET_AMBIGUOUS",
- "TARGET_GROUP_NOT_FOUND",
- "TARGET_GROUP_DISABLED",
- "DUPLICATE_TARGET_GROUP",
- "MESSAGE_UNSUPPORTED",
- "MESSAGE_AMBIGUOUS",
- "ENDPOINT_DISABLED",
- "ENDPOINT_ROUTE_CHANGED",
- "ENDPOINT_HAS_DEPENDENCIES",
- "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
- "ENDPOINT_COMMITTED_CLEANUP_PENDING",
- "DEEP_QUERY_FAILED",
- "PROVIDER_NO_STATE",
- "EVENT_MANAGEMENT_DISABLED",
- "SUBSCRIPTION_IDENTITY_IMMUTABLE",
- "UNSUPPORTED_MEDIA_TYPE",
- "EVENT_PAYLOAD_TOO_LARGE",
- "REQUEST_BODY_TOO_LARGE",
- "EVENT_IDENTITY_CONFLICT",
- "EVENT_INGRESS_QUOTA_EXCEEDED",
- "EVENT_RECEIPT_EXPIRED",
- "EVENT_STORAGE_UNAVAILABLE",
- "EVENT_DEAD_LETTER_NOT_FOUND",
- "EVENT_REDRIVE_CONFLICT",
- "EVENT_REDRIVE_EXPIRED",
- "RECEIPT_CONTEXT_EXPIRED",
- "EVENT_MAINTENANCE_INCOMPLETE",
- "UNKNOWN_INTERFACE",
- "INVALID_CONFIGURATION",
- "INVALID_PLUGIN_MANIFEST",
- "INVALID_ATTRIBUTE",
- "INVALID_PROVIDER_MESSAGE",
- "UNDECLARED_CAPABILITY",
- "PLUGIN_ROUTE_ID_CONFLICT",
- "UNRESOLVED_REFERENCE",
- "INVALID_RELATIONSHIP",
- "RELATIONSHIP_CYCLE",
- "MULTIPLE_PARENTS",
- "FLOW_VALIDATION_FAILED",
- "PROVIDER_SYNC_UNSUPPORTED"
- ],
- "type": "string"
- },
- "family": {
- "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
- "enum": [
- "NOT_FOUND",
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "CONFLICT",
- "GONE",
- "PRECONDITION_FAILED",
- "PRECONDITION_REQUIRED",
- "PAYLOAD_TOO_LARGE",
- "UNSUPPORTED_MEDIA_TYPE",
- "UNPROCESSABLE_ENTITY",
- "LOCKED",
- "TOO_MANY_REQUESTS",
- "BAD_GATEWAY",
- "SERVICE_UNAVAILABLE",
- "GATEWAY_TIMEOUT",
- "NOT_IMPLEMENTED",
- "INTERNAL_SERVER_ERROR",
- "REQUEST_INVALID",
- "AUTHENTICATION",
- "PERMISSION",
- "ENDPOINT_NOT_FOUND",
- "ENDPOINT_STATE_CONFLICT",
- "ENDPOINT_UNAVAILABLE",
- "RATE_LIMIT",
- "PROVIDER_BAD_RESPONSE",
- "PROVIDER_UNAVAILABLE",
- "PROVIDER_TIMEOUT"
- ],
- "type": "string"
- },
- "interface": {
- "description": "Canonical capability interface name the failure applies to, when the failure is interface-specific.",
- "type": "string"
- },
- "message": {
- "description": "Plain-language description of the failure and the suggested fix.",
- "type": "string"
- },
- "pluginRouteId": {
- "description": "Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.",
- "type": "string"
- },
- "relationshipExternalId": {
- "description": "Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.",
- "type": "string"
- },
- "status": {
- "description": "HTTP-equivalent status code of the item failure.",
- "maximum": 599,
- "minimum": 400,
- "type": "integer"
- },
- "version": {
- "description": "Declared capability interface version the failure applies to, when the failure is interface-specific.",
- "type": "string"
- }
- },
- "required": [
- "code",
- "family",
- "status",
- "message"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "family": {
- "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
- "enum": [
- "NOT_FOUND",
- "BAD_REQUEST",
- "UNAUTHORIZED",
- "FORBIDDEN",
- "CONFLICT",
- "GONE",
- "PRECONDITION_FAILED",
- "PRECONDITION_REQUIRED",
- "PAYLOAD_TOO_LARGE",
- "UNSUPPORTED_MEDIA_TYPE",
- "UNPROCESSABLE_ENTITY",
- "LOCKED",
- "TOO_MANY_REQUESTS",
- "BAD_GATEWAY",
- "SERVICE_UNAVAILABLE",
- "GATEWAY_TIMEOUT",
- "NOT_IMPLEMENTED",
- "INTERNAL_SERVER_ERROR",
- "REQUEST_INVALID",
- "AUTHENTICATION",
- "PERMISSION",
- "ENDPOINT_NOT_FOUND",
- "ENDPOINT_STATE_CONFLICT",
- "ENDPOINT_UNAVAILABLE",
- "RATE_LIMIT",
- "PROVIDER_BAD_RESPONSE",
- "PROVIDER_UNAVAILABLE",
- "PROVIDER_TIMEOUT"
- ],
- "type": "string"
- },
- "message": {
- "description": "Plain-language description of the failure and the suggested next action.",
- "type": "string"
- }
- },
- "required": [
- "family",
- "code",
- "message"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "description": "Evaluated batch envelope. COMMITTED and PARTIALLY_SUCCEEDED save all customer operations; PARTIALLY_SUCCEEDED includes at least one PARTIALLY_APPLIED fallback. FAILED saves no rejected customer intent, but retains valid provider truth and the terminal failed receipt after any provider attempt. Failed results list attempted operations as NOT_APPLIED without group etags; errors contains one item per failing operation. Items correlate by requestId, never position.",
+ "properties": {
+ "errors": {
+ "items": {
+ "description": "Error for one operation of an atomic batch, correlated by the operation's `requestId`. `status` is the HTTP status the operation would have returned on its own.\n",
+ "properties": {
+ "code": {
+ "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
+ "enum": [
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "INSUFFICIENT_SCOPE",
+ "NOT_FOUND",
+ "CONFLICT",
+ "UNPROCESSABLE_ENTITY",
+ "UNSUPPORTED_OPERATION",
+ "TOO_MANY_REQUESTS",
+ "SERVICE_UNAVAILABLE",
+ "NOT_IMPLEMENTED",
+ "INTERNAL",
+ "CHECKSUM_MISMATCH",
+ "FILE_TOO_LARGE",
+ "STORAGE_UNAVAILABLE",
+ "INSUFFICIENT_PERMISSIONS",
+ "INVALID_FILE_TYPE",
+ "QUOTA_EXCEEDED",
+ "CONCURRENT_MODIFICATION",
+ "ENDPOINT_UNREACHABLE",
+ "BRIDGE_UNREACHABLE",
+ "CLOUD_CONTROL_DISABLED",
+ "ENDPOINT_BUSY",
+ "ENDPOINT_LOW_POWER",
+ "AUTHORIZATION_CREDENTIAL_INVALID",
+ "AUTHORIZATION_CREDENTIAL_EXPIRED",
+ "INVALID_DIRECTIVE",
+ "INVALID_VALUE",
+ "VALUE_OUT_OF_RANGE",
+ "NOT_SUPPORTED_IN_CURRENT_MODE",
+ "RATE_LIMIT_EXCEEDED",
+ "PROVIDER_SERVICE_UNAVAILABLE",
+ "PROVIDER_TIMEOUT",
+ "PROVIDER_INTERNAL_ERROR",
+ "INVALID_PROVIDER_RESPONSE",
+ "OUTCOME_UNKNOWN",
+ "PRECONDITION_FAILED",
+ "AUTH_LINK_NOT_READY",
+ "AUTH_LINK_NOT_DISCONNECTABLE",
+ "PRECONDITION_REQUIRED",
+ "IDEMPOTENCY_KEY_REQUIRED",
+ "IDEMPOTENCY_KEY_REUSED",
+ "IDEMPOTENCY_KEY_IN_FLIGHT",
+ "IDEMPOTENCY_KEY_INVALID",
+ "GROUP_MERGED",
+ "MULTI_ROOM_UNSUPPORTED",
+ "MAP_NOT_ACTIVE",
+ "TARGET_UNSUPPORTED",
+ "TARGET_AMBIGUOUS",
+ "TARGET_GROUP_NOT_FOUND",
+ "TARGET_GROUP_DISABLED",
+ "DUPLICATE_TARGET_GROUP",
+ "MESSAGE_UNSUPPORTED",
+ "MESSAGE_AMBIGUOUS",
+ "ENDPOINT_DISABLED",
+ "ENDPOINT_ROUTE_CHANGED",
+ "ENDPOINT_HAS_DEPENDENCIES",
+ "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
+ "ENDPOINT_COMMITTED_CLEANUP_PENDING",
+ "DEEP_QUERY_FAILED",
+ "PROVIDER_NO_STATE",
+ "EVENT_MANAGEMENT_DISABLED",
+ "SUBSCRIPTION_IDENTITY_IMMUTABLE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "EVENT_PAYLOAD_TOO_LARGE",
+ "REQUEST_BODY_TOO_LARGE",
+ "EVENT_IDENTITY_CONFLICT",
+ "EVENT_INGRESS_QUOTA_EXCEEDED",
+ "EVENT_RECEIPT_EXPIRED",
+ "EVENT_STORAGE_UNAVAILABLE",
+ "EVENT_DEAD_LETTER_NOT_FOUND",
+ "EVENT_REDRIVE_CONFLICT",
+ "EVENT_REDRIVE_EXPIRED",
+ "RECEIPT_CONTEXT_EXPIRED",
+ "EVENT_MAINTENANCE_INCOMPLETE",
+ "UNKNOWN_INTERFACE",
+ "INVALID_CONFIGURATION",
+ "INVALID_PLUGIN_MANIFEST",
+ "INVALID_ATTRIBUTE",
+ "INVALID_PROVIDER_MESSAGE",
+ "UNDECLARED_CAPABILITY",
+ "PLUGIN_ROUTE_ID_CONFLICT",
+ "UNRESOLVED_REFERENCE",
+ "INVALID_RELATIONSHIP",
+ "RELATIONSHIP_CYCLE",
+ "MULTIPLE_PARENTS",
+ "FLOW_VALIDATION_FAILED",
+ "PROVIDER_SYNC_UNSUPPORTED"
+ ],
+ "type": "string"
+ },
+ "errors": {
+ "description": "Typed validation failures inside this operation when one report contains several rejected routes, interfaces or relationships.",
+ "items": {
+ "description": "One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.\n",
+ "properties": {
+ "code": {
+ "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
+ "enum": [
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "INSUFFICIENT_SCOPE",
+ "NOT_FOUND",
+ "CONFLICT",
+ "UNPROCESSABLE_ENTITY",
+ "UNSUPPORTED_OPERATION",
+ "TOO_MANY_REQUESTS",
+ "SERVICE_UNAVAILABLE",
+ "NOT_IMPLEMENTED",
+ "INTERNAL",
+ "CHECKSUM_MISMATCH",
+ "FILE_TOO_LARGE",
+ "STORAGE_UNAVAILABLE",
+ "INSUFFICIENT_PERMISSIONS",
+ "INVALID_FILE_TYPE",
+ "QUOTA_EXCEEDED",
+ "CONCURRENT_MODIFICATION",
+ "ENDPOINT_UNREACHABLE",
+ "BRIDGE_UNREACHABLE",
+ "CLOUD_CONTROL_DISABLED",
+ "ENDPOINT_BUSY",
+ "ENDPOINT_LOW_POWER",
+ "AUTHORIZATION_CREDENTIAL_INVALID",
+ "AUTHORIZATION_CREDENTIAL_EXPIRED",
+ "INVALID_DIRECTIVE",
+ "INVALID_VALUE",
+ "VALUE_OUT_OF_RANGE",
+ "NOT_SUPPORTED_IN_CURRENT_MODE",
+ "RATE_LIMIT_EXCEEDED",
+ "PROVIDER_SERVICE_UNAVAILABLE",
+ "PROVIDER_TIMEOUT",
+ "PROVIDER_INTERNAL_ERROR",
+ "INVALID_PROVIDER_RESPONSE",
+ "OUTCOME_UNKNOWN",
+ "PRECONDITION_FAILED",
+ "AUTH_LINK_NOT_READY",
+ "AUTH_LINK_NOT_DISCONNECTABLE",
+ "PRECONDITION_REQUIRED",
+ "IDEMPOTENCY_KEY_REQUIRED",
+ "IDEMPOTENCY_KEY_REUSED",
+ "IDEMPOTENCY_KEY_IN_FLIGHT",
+ "IDEMPOTENCY_KEY_INVALID",
+ "GROUP_MERGED",
+ "MULTI_ROOM_UNSUPPORTED",
+ "MAP_NOT_ACTIVE",
+ "TARGET_UNSUPPORTED",
+ "TARGET_AMBIGUOUS",
+ "TARGET_GROUP_NOT_FOUND",
+ "TARGET_GROUP_DISABLED",
+ "DUPLICATE_TARGET_GROUP",
+ "MESSAGE_UNSUPPORTED",
+ "MESSAGE_AMBIGUOUS",
+ "ENDPOINT_DISABLED",
+ "ENDPOINT_ROUTE_CHANGED",
+ "ENDPOINT_HAS_DEPENDENCIES",
+ "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
+ "ENDPOINT_COMMITTED_CLEANUP_PENDING",
+ "DEEP_QUERY_FAILED",
+ "PROVIDER_NO_STATE",
+ "EVENT_MANAGEMENT_DISABLED",
+ "SUBSCRIPTION_IDENTITY_IMMUTABLE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "EVENT_PAYLOAD_TOO_LARGE",
+ "REQUEST_BODY_TOO_LARGE",
+ "EVENT_IDENTITY_CONFLICT",
+ "EVENT_INGRESS_QUOTA_EXCEEDED",
+ "EVENT_RECEIPT_EXPIRED",
+ "EVENT_STORAGE_UNAVAILABLE",
+ "EVENT_DEAD_LETTER_NOT_FOUND",
+ "EVENT_REDRIVE_CONFLICT",
+ "EVENT_REDRIVE_EXPIRED",
+ "RECEIPT_CONTEXT_EXPIRED",
+ "EVENT_MAINTENANCE_INCOMPLETE",
+ "UNKNOWN_INTERFACE",
+ "INVALID_CONFIGURATION",
+ "INVALID_PLUGIN_MANIFEST",
+ "INVALID_ATTRIBUTE",
+ "INVALID_PROVIDER_MESSAGE",
+ "UNDECLARED_CAPABILITY",
+ "PLUGIN_ROUTE_ID_CONFLICT",
+ "UNRESOLVED_REFERENCE",
+ "INVALID_RELATIONSHIP",
+ "RELATIONSHIP_CYCLE",
+ "MULTIPLE_PARENTS",
+ "FLOW_VALIDATION_FAILED",
+ "PROVIDER_SYNC_UNSUPPORTED"
+ ],
+ "type": "string"
+ },
+ "family": {
+ "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
+ "enum": [
+ "NOT_FOUND",
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "CONFLICT",
+ "GONE",
+ "PRECONDITION_FAILED",
+ "PRECONDITION_REQUIRED",
+ "PAYLOAD_TOO_LARGE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "UNPROCESSABLE_ENTITY",
+ "LOCKED",
+ "TOO_MANY_REQUESTS",
+ "BAD_GATEWAY",
+ "SERVICE_UNAVAILABLE",
+ "GATEWAY_TIMEOUT",
+ "NOT_IMPLEMENTED",
+ "INTERNAL_SERVER_ERROR",
+ "REQUEST_INVALID",
+ "AUTHENTICATION",
+ "PERMISSION",
+ "ENDPOINT_NOT_FOUND",
+ "ENDPOINT_STATE_CONFLICT",
+ "ENDPOINT_UNAVAILABLE",
+ "RATE_LIMIT",
+ "PROVIDER_BAD_RESPONSE",
+ "PROVIDER_UNAVAILABLE",
+ "PROVIDER_TIMEOUT"
+ ],
+ "type": "string"
+ },
+ "interface": {
+ "description": "Canonical capability interface name the failure applies to, when the failure is interface-specific.",
+ "type": "string"
+ },
+ "message": {
+ "description": "Plain-language description of the failure and the suggested fix.",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.",
+ "type": "string"
+ },
+ "relationshipExternalId": {
+ "description": "Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.",
+ "type": "string"
+ },
+ "status": {
+ "description": "HTTP-equivalent status code of the item failure.",
+ "maximum": 599,
+ "minimum": 400,
+ "type": "integer"
+ },
+ "version": {
+ "description": "Declared capability interface version the failure applies to, when the failure is interface-specific.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "family",
+ "status",
+ "message"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "family": {
+ "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
+ "enum": [
+ "NOT_FOUND",
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "CONFLICT",
+ "GONE",
+ "PRECONDITION_FAILED",
+ "PRECONDITION_REQUIRED",
+ "PAYLOAD_TOO_LARGE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "UNPROCESSABLE_ENTITY",
+ "LOCKED",
+ "TOO_MANY_REQUESTS",
+ "BAD_GATEWAY",
+ "SERVICE_UNAVAILABLE",
+ "GATEWAY_TIMEOUT",
+ "NOT_IMPLEMENTED",
+ "INTERNAL_SERVER_ERROR",
+ "REQUEST_INVALID",
+ "AUTHENTICATION",
+ "PERMISSION",
+ "ENDPOINT_NOT_FOUND",
+ "ENDPOINT_STATE_CONFLICT",
+ "ENDPOINT_UNAVAILABLE",
+ "RATE_LIMIT",
+ "PROVIDER_BAD_RESPONSE",
+ "PROVIDER_UNAVAILABLE",
+ "PROVIDER_TIMEOUT"
+ ],
+ "type": "string"
+ },
+ "message": {
+ "description": "Plain-language description of the failure and the suggested next action.",
+ "type": "string"
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "resourceId": {
+ "description": "The resource the failure applies to, when it is not the operation's primary target.",
+ "type": "string"
+ },
+ "status": {
+ "description": "HTTP-equivalent status code of the item failure.",
+ "maximum": 599,
+ "minimum": 400,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "requestId",
+ "code",
+ "family",
+ "status",
+ "message"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "results": {
+ "items": {
+ "description": "One operation outcome correlated by requestId. Applied results use final committed group etags; MOVE_MEMBER returns source and target. NOT_APPLIED reports attempted provider dispatches from a failed customer batch without group, source or target etags. Dispatch errors remain attached to their entries. Operations that reached no provider are omitted from failed batch results.",
+ "properties": {
+ "deletedGroupId": {
+ "description": "The deleted group ID (`DELETE_GROUP`).",
+ "type": "string"
+ },
+ "group": {
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ },
+ "operation": {
+ "description": "Discriminator of an endpoint group management operation.",
+ "enum": [
+ "CREATE_GROUP",
+ "DELETE_GROUP",
+ "SET_NAME",
+ "ADD_MEMBERS",
+ "REMOVE_MEMBERS",
+ "MERGE_INTO",
+ "SET_ENABLEMENT",
+ "MOVE_MEMBER",
+ "SET_GROUP_ROUTE_ENABLEMENT"
+ ],
+ "type": "string"
+ },
+ "providerDispatches": {
+ "description": "This operation's provider messages; an empty array is explicit.",
+ "items": {
+ "description": "One provider message for this operation. SUCCEEDED requires a valid read-back reply establishing the requested condition. Provider identities are present only with the same native-route or account read visibility required by the public query projection. An authorized write can still return a redacted dispatch outcome; its namespace, name, status, reason and error code remain. Errors for hidden metadata use a generic message and omit details.",
+ "properties": {
+ "authLinkId": {
+ "description": "The provider account authorization link ID; omitted without metadata read visibility, empty for a readable account without a link.",
+ "type": "string"
+ },
+ "error": {
+ "description": "The one Port OS error shape, returned by every REST error response and every MCP tool error. `code` names the specific failure and `family` its broad class; both are closed enums, so clients branch on them and show `message`, which says what failed and what to do next.",
+ "properties": {
+ "code": {
+ "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
+ "enum": [
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "INSUFFICIENT_SCOPE",
+ "NOT_FOUND",
+ "CONFLICT",
+ "UNPROCESSABLE_ENTITY",
+ "UNSUPPORTED_OPERATION",
+ "TOO_MANY_REQUESTS",
+ "SERVICE_UNAVAILABLE",
+ "NOT_IMPLEMENTED",
+ "INTERNAL",
+ "CHECKSUM_MISMATCH",
+ "FILE_TOO_LARGE",
+ "STORAGE_UNAVAILABLE",
+ "INSUFFICIENT_PERMISSIONS",
+ "INVALID_FILE_TYPE",
+ "QUOTA_EXCEEDED",
+ "CONCURRENT_MODIFICATION",
+ "ENDPOINT_UNREACHABLE",
+ "BRIDGE_UNREACHABLE",
+ "CLOUD_CONTROL_DISABLED",
+ "ENDPOINT_BUSY",
+ "ENDPOINT_LOW_POWER",
+ "AUTHORIZATION_CREDENTIAL_INVALID",
+ "AUTHORIZATION_CREDENTIAL_EXPIRED",
+ "INVALID_DIRECTIVE",
+ "INVALID_VALUE",
+ "VALUE_OUT_OF_RANGE",
+ "NOT_SUPPORTED_IN_CURRENT_MODE",
+ "RATE_LIMIT_EXCEEDED",
+ "PROVIDER_SERVICE_UNAVAILABLE",
+ "PROVIDER_TIMEOUT",
+ "PROVIDER_INTERNAL_ERROR",
+ "INVALID_PROVIDER_RESPONSE",
+ "OUTCOME_UNKNOWN",
+ "PRECONDITION_FAILED",
+ "AUTH_LINK_NOT_READY",
+ "AUTH_LINK_NOT_DISCONNECTABLE",
+ "PRECONDITION_REQUIRED",
+ "IDEMPOTENCY_KEY_REQUIRED",
+ "IDEMPOTENCY_KEY_REUSED",
+ "IDEMPOTENCY_KEY_IN_FLIGHT",
+ "IDEMPOTENCY_KEY_INVALID",
+ "GROUP_MERGED",
+ "MULTI_ROOM_UNSUPPORTED",
+ "MAP_NOT_ACTIVE",
+ "TARGET_UNSUPPORTED",
+ "TARGET_AMBIGUOUS",
+ "TARGET_GROUP_NOT_FOUND",
+ "TARGET_GROUP_DISABLED",
+ "DUPLICATE_TARGET_GROUP",
+ "MESSAGE_UNSUPPORTED",
+ "MESSAGE_AMBIGUOUS",
+ "ENDPOINT_DISABLED",
+ "ENDPOINT_ROUTE_CHANGED",
+ "ENDPOINT_HAS_DEPENDENCIES",
+ "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
+ "ENDPOINT_COMMITTED_CLEANUP_PENDING",
+ "DEEP_QUERY_FAILED",
+ "PROVIDER_NO_STATE",
+ "EVENT_MANAGEMENT_DISABLED",
+ "SUBSCRIPTION_IDENTITY_IMMUTABLE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "EVENT_PAYLOAD_TOO_LARGE",
+ "REQUEST_BODY_TOO_LARGE",
+ "EVENT_IDENTITY_CONFLICT",
+ "EVENT_INGRESS_QUOTA_EXCEEDED",
+ "EVENT_RECEIPT_EXPIRED",
+ "EVENT_STORAGE_UNAVAILABLE",
+ "EVENT_DEAD_LETTER_NOT_FOUND",
+ "EVENT_REDRIVE_CONFLICT",
+ "EVENT_REDRIVE_EXPIRED",
+ "RECEIPT_CONTEXT_EXPIRED",
+ "EVENT_MAINTENANCE_INCOMPLETE",
+ "UNKNOWN_INTERFACE",
+ "INVALID_CONFIGURATION",
+ "INVALID_PLUGIN_MANIFEST",
+ "INVALID_ATTRIBUTE",
+ "INVALID_PROVIDER_MESSAGE",
+ "UNDECLARED_CAPABILITY",
+ "PLUGIN_ROUTE_ID_CONFLICT",
+ "UNRESOLVED_REFERENCE",
+ "INVALID_RELATIONSHIP",
+ "RELATIONSHIP_CYCLE",
+ "MULTIPLE_PARENTS",
+ "FLOW_VALIDATION_FAILED",
+ "PROVIDER_SYNC_UNSUPPORTED"
+ ],
+ "type": "string"
+ },
+ "details": {
+ "description": "Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.\n",
+ "properties": {
+ "actual": {
+ "description": "String representation of the submitted value when the plugin can safely report it.",
+ "type": "string"
+ },
+ "correlationId": {
+ "description": "Provider or plugin correlation ID useful for support.",
+ "type": "string"
+ },
+ "correlationToken": {
+ "description": "Token that correlates an outcome-unknown dispatch with its eventual result.",
+ "type": "string"
+ },
+ "currentMode": {
+ "description": "Current endpoint mode when `code` is `NOT_SUPPORTED_IN_CURRENT_MODE`.",
+ "type": "string"
+ },
+ "directive": {
+ "description": "Message namespace and name or provider directive that failed.",
+ "type": "string"
+ },
+ "discoveryEndpointId": {
+ "description": "Port OS provider endpoint (type ENDPOINT_PLUGIN) of the connection to send `discover-routes` to when `code` is `TARGET_UNSUPPORTED` because the route must be rediscovered.",
+ "type": "string"
+ },
+ "endpointId": {
+ "description": "Port OS endpoint ID involved in the failed dispatch.",
+ "type": "string"
+ },
+ "fieldErrors": {
+ "description": "The request fields that were rejected, when the error is about the request's content.",
+ "items": {
+ "description": "One rejected request field of an error.",
+ "properties": {
+ "field": {
+ "description": "Name or JSON path of the rejected field.",
+ "type": "string"
+ },
+ "reason": {
+ "description": "Why the field was rejected and what an accepted value looks like.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "field",
+ "reason"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "maximum": {
+ "description": "Maximum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
+ "type": "number"
+ },
+ "minimum": {
+ "description": "Minimum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
+ "type": "number"
+ },
+ "parameter": {
+ "description": "Request parameter or capability value that caused the failure.",
+ "type": "string"
+ },
+ "pluginId": {
+ "description": "Port OS plugin ID that reported the failure.",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "Plugin-owned route identifier involved in the failed dispatch.",
+ "type": "string"
+ },
+ "provider": {
+ "description": "Third-party provider or bridge name that reported the failure.",
+ "type": "string"
+ },
+ "providerCode": {
+ "description": "The third-party provider's own error code, for support. It is opaque and provider-specific; branch on `code` and `family` instead.",
+ "type": "string"
+ },
+ "retryAfterSeconds": {
+ "description": "Suggested retry delay for rate-limit or provider-unavailable failures.",
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "errors": {
+ "description": "Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.\n",
+ "items": {
+ "description": "One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.\n",
+ "properties": {
+ "code": {
+ "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
+ "enum": [
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "INSUFFICIENT_SCOPE",
+ "NOT_FOUND",
+ "CONFLICT",
+ "UNPROCESSABLE_ENTITY",
+ "UNSUPPORTED_OPERATION",
+ "TOO_MANY_REQUESTS",
+ "SERVICE_UNAVAILABLE",
+ "NOT_IMPLEMENTED",
+ "INTERNAL",
+ "CHECKSUM_MISMATCH",
+ "FILE_TOO_LARGE",
+ "STORAGE_UNAVAILABLE",
+ "INSUFFICIENT_PERMISSIONS",
+ "INVALID_FILE_TYPE",
+ "QUOTA_EXCEEDED",
+ "CONCURRENT_MODIFICATION",
+ "ENDPOINT_UNREACHABLE",
+ "BRIDGE_UNREACHABLE",
+ "CLOUD_CONTROL_DISABLED",
+ "ENDPOINT_BUSY",
+ "ENDPOINT_LOW_POWER",
+ "AUTHORIZATION_CREDENTIAL_INVALID",
+ "AUTHORIZATION_CREDENTIAL_EXPIRED",
+ "INVALID_DIRECTIVE",
+ "INVALID_VALUE",
+ "VALUE_OUT_OF_RANGE",
+ "NOT_SUPPORTED_IN_CURRENT_MODE",
+ "RATE_LIMIT_EXCEEDED",
+ "PROVIDER_SERVICE_UNAVAILABLE",
+ "PROVIDER_TIMEOUT",
+ "PROVIDER_INTERNAL_ERROR",
+ "INVALID_PROVIDER_RESPONSE",
+ "OUTCOME_UNKNOWN",
+ "PRECONDITION_FAILED",
+ "AUTH_LINK_NOT_READY",
+ "AUTH_LINK_NOT_DISCONNECTABLE",
+ "PRECONDITION_REQUIRED",
+ "IDEMPOTENCY_KEY_REQUIRED",
+ "IDEMPOTENCY_KEY_REUSED",
+ "IDEMPOTENCY_KEY_IN_FLIGHT",
+ "IDEMPOTENCY_KEY_INVALID",
+ "GROUP_MERGED",
+ "MULTI_ROOM_UNSUPPORTED",
+ "MAP_NOT_ACTIVE",
+ "TARGET_UNSUPPORTED",
+ "TARGET_AMBIGUOUS",
+ "TARGET_GROUP_NOT_FOUND",
+ "TARGET_GROUP_DISABLED",
+ "DUPLICATE_TARGET_GROUP",
+ "MESSAGE_UNSUPPORTED",
+ "MESSAGE_AMBIGUOUS",
+ "ENDPOINT_DISABLED",
+ "ENDPOINT_ROUTE_CHANGED",
+ "ENDPOINT_HAS_DEPENDENCIES",
+ "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
+ "ENDPOINT_COMMITTED_CLEANUP_PENDING",
+ "DEEP_QUERY_FAILED",
+ "PROVIDER_NO_STATE",
+ "EVENT_MANAGEMENT_DISABLED",
+ "SUBSCRIPTION_IDENTITY_IMMUTABLE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "EVENT_PAYLOAD_TOO_LARGE",
+ "REQUEST_BODY_TOO_LARGE",
+ "EVENT_IDENTITY_CONFLICT",
+ "EVENT_INGRESS_QUOTA_EXCEEDED",
+ "EVENT_RECEIPT_EXPIRED",
+ "EVENT_STORAGE_UNAVAILABLE",
+ "EVENT_DEAD_LETTER_NOT_FOUND",
+ "EVENT_REDRIVE_CONFLICT",
+ "EVENT_REDRIVE_EXPIRED",
+ "RECEIPT_CONTEXT_EXPIRED",
+ "EVENT_MAINTENANCE_INCOMPLETE",
+ "UNKNOWN_INTERFACE",
+ "INVALID_CONFIGURATION",
+ "INVALID_PLUGIN_MANIFEST",
+ "INVALID_ATTRIBUTE",
+ "INVALID_PROVIDER_MESSAGE",
+ "UNDECLARED_CAPABILITY",
+ "PLUGIN_ROUTE_ID_CONFLICT",
+ "UNRESOLVED_REFERENCE",
+ "INVALID_RELATIONSHIP",
+ "RELATIONSHIP_CYCLE",
+ "MULTIPLE_PARENTS",
+ "FLOW_VALIDATION_FAILED",
+ "PROVIDER_SYNC_UNSUPPORTED"
+ ],
+ "type": "string"
+ },
+ "family": {
+ "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
+ "enum": [
+ "NOT_FOUND",
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "CONFLICT",
+ "GONE",
+ "PRECONDITION_FAILED",
+ "PRECONDITION_REQUIRED",
+ "PAYLOAD_TOO_LARGE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "UNPROCESSABLE_ENTITY",
+ "LOCKED",
+ "TOO_MANY_REQUESTS",
+ "BAD_GATEWAY",
+ "SERVICE_UNAVAILABLE",
+ "GATEWAY_TIMEOUT",
+ "NOT_IMPLEMENTED",
+ "INTERNAL_SERVER_ERROR",
+ "REQUEST_INVALID",
+ "AUTHENTICATION",
+ "PERMISSION",
+ "ENDPOINT_NOT_FOUND",
+ "ENDPOINT_STATE_CONFLICT",
+ "ENDPOINT_UNAVAILABLE",
+ "RATE_LIMIT",
+ "PROVIDER_BAD_RESPONSE",
+ "PROVIDER_UNAVAILABLE",
+ "PROVIDER_TIMEOUT"
+ ],
+ "type": "string"
+ },
+ "interface": {
+ "description": "Canonical capability interface name the failure applies to, when the failure is interface-specific.",
+ "type": "string"
+ },
+ "message": {
+ "description": "Plain-language description of the failure and the suggested fix.",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.",
+ "type": "string"
+ },
+ "relationshipExternalId": {
+ "description": "Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.",
+ "type": "string"
+ },
+ "status": {
+ "description": "HTTP-equivalent status code of the item failure.",
+ "maximum": 599,
+ "minimum": 400,
+ "type": "integer"
+ },
+ "version": {
+ "description": "Declared capability interface version the failure applies to, when the failure is interface-specific.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "family",
+ "status",
+ "message"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "family": {
+ "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
+ "enum": [
+ "NOT_FOUND",
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "CONFLICT",
+ "GONE",
+ "PRECONDITION_FAILED",
+ "PRECONDITION_REQUIRED",
+ "PAYLOAD_TOO_LARGE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "UNPROCESSABLE_ENTITY",
+ "LOCKED",
+ "TOO_MANY_REQUESTS",
+ "BAD_GATEWAY",
+ "SERVICE_UNAVAILABLE",
+ "GATEWAY_TIMEOUT",
+ "NOT_IMPLEMENTED",
+ "INTERNAL_SERVER_ERROR",
+ "REQUEST_INVALID",
+ "AUTHENTICATION",
+ "PERMISSION",
+ "ENDPOINT_NOT_FOUND",
+ "ENDPOINT_STATE_CONFLICT",
+ "ENDPOINT_UNAVAILABLE",
+ "RATE_LIMIT",
+ "PROVIDER_BAD_RESPONSE",
+ "PROVIDER_UNAVAILABLE",
+ "PROVIDER_TIMEOUT"
+ ],
+ "type": "string"
+ },
+ "message": {
+ "description": "Plain-language description of the failure and the suggested next action.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "family",
+ "code",
+ "message"
+ ],
+ "type": "object"
+ },
+ "groupRouteId": {
+ "description": "The provider-native group route ID within this plugin and account, omitted without native-route read visibility.",
+ "type": "string"
+ },
+ "impliedRemovals": {
+ "description": "Authorized native memberships displaced by an explicit move.",
+ "items": {
+ "description": "In-scope membership removals implied by an exclusive provider move.",
+ "properties": {
+ "groupRouteId": {
+ "description": "The Port OS group route affected by the removal.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "memberEndpointIds": {
+ "description": "Endpoint members removed from this route.",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "type": "array",
+ "uniqueItems": true
+ }
+ },
+ "required": [
+ "groupRouteId",
+ "memberEndpointIds"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "name": {
+ "description": "The canonical message name.",
+ "type": "string"
+ },
+ "namespace": {
+ "description": "The message capability namespace.",
+ "type": "string"
+ },
+ "pluginId": {
+ "description": "The admitted provider plugin ID, omitted when provider metadata is not readable.",
+ "type": "string"
+ },
+ "reason": {
+ "description": "Why no provider dispatch was sent. NOT_DECLARED means the provider does not declare the message. OUTSIDE_PRINCIPAL means native mutations are limited to accounts owned by the original caller; sharing a group or endpoint does not grant native account-management authority. Local intent can still apply without dispatching to the foreign account.",
+ "enum": [
+ "NOT_DECLARED",
+ "OUTSIDE_PRINCIPAL"
+ ],
+ "type": "string"
+ },
+ "status": {
+ "description": "A planned, verified, failed or undeclared provider dispatch; a timeout is FAILED.",
+ "enum": [
+ "PLANNED",
+ "SUCCEEDED",
+ "FAILED",
+ "NOT_SUPPORTED"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "namespace",
+ "name",
+ "status"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "redirects": {
+ "description": "Redirects written by `MERGE_INTO`.",
+ "items": {
+ "description": "A merged-away group ID and the group it now redirects to. Reads and control follow redirects; mutations fail with GROUP_MERGED.",
+ "properties": {
+ "from": {
+ "description": "The merged-away group ID.",
+ "type": "string"
+ },
+ "to": {
+ "description": "The group it redirects to.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "from",
+ "to"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "requestId": {
+ "description": "Client-chosen identifier for one operation in a batch request. It must be unique within the request and is echoed in the matching result or error so items are correlated by ID, never by position.\n",
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "source": {
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ },
+ "status": {
+ "description": "APPLIED commits without a failed-dispatch fallback; PARTIALLY_APPLIED commits with one. NOT_APPLIED reports provider attempts from a failed customer batch and carries no group etag.",
+ "enum": [
+ "APPLIED",
+ "PARTIALLY_APPLIED",
+ "NOT_APPLIED"
+ ],
+ "type": "string"
+ },
+ "target": {
+ "description": "A group addressed together with the etag the client last read, validated inside the management transaction.",
+ "properties": {
+ "etag": {
+ "description": "The group's `etag` as last read by the client.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "groupId": {
+ "description": "The endpoint group ID.",
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "groupId",
+ "etag"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "requestId",
+ "operation",
+ "status",
+ "providerDispatches"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "COMMITTED means all customer operations applied. PARTIALLY_SUCCEEDED means they applied with a reported provider fallback. FAILED means customer intent did not commit; operation-specific contracts state whether already received provider observations are retained.",
+ "enum": [
+ "COMMITTED",
+ "FAILED",
+ "PARTIALLY_SUCCEEDED"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "results",
+ "errors"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "description": "The one Port OS error shape, returned by every REST error response and every MCP tool error. `code` names the specific failure and `family` its broad class; both are closed enums, so clients branch on them and show `message`, which says what failed and what to do next.",
+ "properties": {
+ "code": {
+ "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
+ "enum": [
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "INSUFFICIENT_SCOPE",
+ "NOT_FOUND",
+ "CONFLICT",
+ "UNPROCESSABLE_ENTITY",
+ "UNSUPPORTED_OPERATION",
+ "TOO_MANY_REQUESTS",
+ "SERVICE_UNAVAILABLE",
+ "NOT_IMPLEMENTED",
+ "INTERNAL",
+ "CHECKSUM_MISMATCH",
+ "FILE_TOO_LARGE",
+ "STORAGE_UNAVAILABLE",
+ "INSUFFICIENT_PERMISSIONS",
+ "INVALID_FILE_TYPE",
+ "QUOTA_EXCEEDED",
+ "CONCURRENT_MODIFICATION",
+ "ENDPOINT_UNREACHABLE",
+ "BRIDGE_UNREACHABLE",
+ "CLOUD_CONTROL_DISABLED",
+ "ENDPOINT_BUSY",
+ "ENDPOINT_LOW_POWER",
+ "AUTHORIZATION_CREDENTIAL_INVALID",
+ "AUTHORIZATION_CREDENTIAL_EXPIRED",
+ "INVALID_DIRECTIVE",
+ "INVALID_VALUE",
+ "VALUE_OUT_OF_RANGE",
+ "NOT_SUPPORTED_IN_CURRENT_MODE",
+ "RATE_LIMIT_EXCEEDED",
+ "PROVIDER_SERVICE_UNAVAILABLE",
+ "PROVIDER_TIMEOUT",
+ "PROVIDER_INTERNAL_ERROR",
+ "INVALID_PROVIDER_RESPONSE",
+ "OUTCOME_UNKNOWN",
+ "PRECONDITION_FAILED",
+ "AUTH_LINK_NOT_READY",
+ "AUTH_LINK_NOT_DISCONNECTABLE",
+ "PRECONDITION_REQUIRED",
+ "IDEMPOTENCY_KEY_REQUIRED",
+ "IDEMPOTENCY_KEY_REUSED",
+ "IDEMPOTENCY_KEY_IN_FLIGHT",
+ "IDEMPOTENCY_KEY_INVALID",
+ "GROUP_MERGED",
+ "MULTI_ROOM_UNSUPPORTED",
+ "MAP_NOT_ACTIVE",
+ "TARGET_UNSUPPORTED",
+ "TARGET_AMBIGUOUS",
+ "TARGET_GROUP_NOT_FOUND",
+ "TARGET_GROUP_DISABLED",
+ "DUPLICATE_TARGET_GROUP",
+ "MESSAGE_UNSUPPORTED",
+ "MESSAGE_AMBIGUOUS",
+ "ENDPOINT_DISABLED",
+ "ENDPOINT_ROUTE_CHANGED",
+ "ENDPOINT_HAS_DEPENDENCIES",
+ "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
+ "ENDPOINT_COMMITTED_CLEANUP_PENDING",
+ "DEEP_QUERY_FAILED",
+ "PROVIDER_NO_STATE",
+ "EVENT_MANAGEMENT_DISABLED",
+ "SUBSCRIPTION_IDENTITY_IMMUTABLE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "EVENT_PAYLOAD_TOO_LARGE",
+ "REQUEST_BODY_TOO_LARGE",
+ "EVENT_IDENTITY_CONFLICT",
+ "EVENT_INGRESS_QUOTA_EXCEEDED",
+ "EVENT_RECEIPT_EXPIRED",
+ "EVENT_STORAGE_UNAVAILABLE",
+ "EVENT_DEAD_LETTER_NOT_FOUND",
+ "EVENT_REDRIVE_CONFLICT",
+ "EVENT_REDRIVE_EXPIRED",
+ "RECEIPT_CONTEXT_EXPIRED",
+ "EVENT_MAINTENANCE_INCOMPLETE",
+ "UNKNOWN_INTERFACE",
+ "INVALID_CONFIGURATION",
+ "INVALID_PLUGIN_MANIFEST",
+ "INVALID_ATTRIBUTE",
+ "INVALID_PROVIDER_MESSAGE",
+ "UNDECLARED_CAPABILITY",
+ "PLUGIN_ROUTE_ID_CONFLICT",
+ "UNRESOLVED_REFERENCE",
+ "INVALID_RELATIONSHIP",
+ "RELATIONSHIP_CYCLE",
+ "MULTIPLE_PARENTS",
+ "FLOW_VALIDATION_FAILED",
+ "PROVIDER_SYNC_UNSUPPORTED"
+ ],
+ "type": "string"
+ },
+ "details": {
+ "description": "Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.\n",
+ "properties": {
+ "actual": {
+ "description": "String representation of the submitted value when the plugin can safely report it.",
+ "type": "string"
+ },
+ "correlationId": {
+ "description": "Provider or plugin correlation ID useful for support.",
+ "type": "string"
+ },
+ "correlationToken": {
+ "description": "Token that correlates an outcome-unknown dispatch with its eventual result.",
+ "type": "string"
+ },
+ "currentMode": {
+ "description": "Current endpoint mode when `code` is `NOT_SUPPORTED_IN_CURRENT_MODE`.",
+ "type": "string"
+ },
+ "directive": {
+ "description": "Message namespace and name or provider directive that failed.",
+ "type": "string"
+ },
+ "discoveryEndpointId": {
+ "description": "Port OS provider endpoint (type ENDPOINT_PLUGIN) of the connection to send `discover-routes` to when `code` is `TARGET_UNSUPPORTED` because the route must be rediscovered.",
+ "type": "string"
+ },
+ "endpointId": {
+ "description": "Port OS endpoint ID involved in the failed dispatch.",
+ "type": "string"
+ },
+ "fieldErrors": {
+ "description": "The request fields that were rejected, when the error is about the request's content.",
+ "items": {
+ "description": "One rejected request field of an error.",
+ "properties": {
+ "field": {
+ "description": "Name or JSON path of the rejected field.",
+ "type": "string"
+ },
+ "reason": {
+ "description": "Why the field was rejected and what an accepted value looks like.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "field",
+ "reason"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "maximum": {
+ "description": "Maximum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
+ "type": "number"
+ },
+ "minimum": {
+ "description": "Minimum accepted value when `code` is `VALUE_OUT_OF_RANGE`.",
+ "type": "number"
+ },
+ "parameter": {
+ "description": "Request parameter or capability value that caused the failure.",
+ "type": "string"
+ },
+ "pluginId": {
+ "description": "Port OS plugin ID that reported the failure.",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "Plugin-owned route identifier involved in the failed dispatch.",
+ "type": "string"
+ },
+ "provider": {
+ "description": "Third-party provider or bridge name that reported the failure.",
+ "type": "string"
+ },
+ "providerCode": {
+ "description": "The third-party provider's own error code, for support. It is opaque and provider-specific; branch on `code` and `family` instead.",
+ "type": "string"
+ },
+ "retryAfterSeconds": {
+ "description": "Suggested retry delay for rate-limit or provider-unavailable failures.",
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "type": "object"
+ },
+ "errors": {
+ "description": "Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.\n",
+ "items": {
+ "description": "One rejected discovery item of a `SynchronizationRequest`, keyed by the plugin-owned identity of the rejected item: `pluginRouteId` for a route or group route, or `relationshipExternalId` for a relationship. Exactly one of the two is set. It shares the `code`, `family`, `status` and `message` fields of `BatchItemError`; discovery items are keyed by plugin-owned identity because they carry no `requestId`. A request with any rejected item is rejected as a whole and lists every rejected item.\n",
+ "properties": {
+ "code": {
+ "description": "The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.",
+ "enum": [
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "INSUFFICIENT_SCOPE",
+ "NOT_FOUND",
+ "CONFLICT",
+ "UNPROCESSABLE_ENTITY",
+ "UNSUPPORTED_OPERATION",
+ "TOO_MANY_REQUESTS",
+ "SERVICE_UNAVAILABLE",
+ "NOT_IMPLEMENTED",
+ "INTERNAL",
+ "CHECKSUM_MISMATCH",
+ "FILE_TOO_LARGE",
+ "STORAGE_UNAVAILABLE",
+ "INSUFFICIENT_PERMISSIONS",
+ "INVALID_FILE_TYPE",
+ "QUOTA_EXCEEDED",
+ "CONCURRENT_MODIFICATION",
+ "ENDPOINT_UNREACHABLE",
+ "BRIDGE_UNREACHABLE",
+ "CLOUD_CONTROL_DISABLED",
+ "ENDPOINT_BUSY",
+ "ENDPOINT_LOW_POWER",
+ "AUTHORIZATION_CREDENTIAL_INVALID",
+ "AUTHORIZATION_CREDENTIAL_EXPIRED",
+ "INVALID_DIRECTIVE",
+ "INVALID_VALUE",
+ "VALUE_OUT_OF_RANGE",
+ "NOT_SUPPORTED_IN_CURRENT_MODE",
+ "RATE_LIMIT_EXCEEDED",
+ "PROVIDER_SERVICE_UNAVAILABLE",
+ "PROVIDER_TIMEOUT",
+ "PROVIDER_INTERNAL_ERROR",
+ "INVALID_PROVIDER_RESPONSE",
+ "OUTCOME_UNKNOWN",
+ "PRECONDITION_FAILED",
+ "AUTH_LINK_NOT_READY",
+ "AUTH_LINK_NOT_DISCONNECTABLE",
+ "PRECONDITION_REQUIRED",
+ "IDEMPOTENCY_KEY_REQUIRED",
+ "IDEMPOTENCY_KEY_REUSED",
+ "IDEMPOTENCY_KEY_IN_FLIGHT",
+ "IDEMPOTENCY_KEY_INVALID",
+ "GROUP_MERGED",
+ "MULTI_ROOM_UNSUPPORTED",
+ "MAP_NOT_ACTIVE",
+ "TARGET_UNSUPPORTED",
+ "TARGET_AMBIGUOUS",
+ "TARGET_GROUP_NOT_FOUND",
+ "TARGET_GROUP_DISABLED",
+ "DUPLICATE_TARGET_GROUP",
+ "MESSAGE_UNSUPPORTED",
+ "MESSAGE_AMBIGUOUS",
+ "ENDPOINT_DISABLED",
+ "ENDPOINT_ROUTE_CHANGED",
+ "ENDPOINT_HAS_DEPENDENCIES",
+ "ENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVE",
+ "ENDPOINT_COMMITTED_CLEANUP_PENDING",
+ "DEEP_QUERY_FAILED",
+ "PROVIDER_NO_STATE",
+ "EVENT_MANAGEMENT_DISABLED",
+ "SUBSCRIPTION_IDENTITY_IMMUTABLE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "EVENT_PAYLOAD_TOO_LARGE",
+ "REQUEST_BODY_TOO_LARGE",
+ "EVENT_IDENTITY_CONFLICT",
+ "EVENT_INGRESS_QUOTA_EXCEEDED",
+ "EVENT_RECEIPT_EXPIRED",
+ "EVENT_STORAGE_UNAVAILABLE",
+ "EVENT_DEAD_LETTER_NOT_FOUND",
+ "EVENT_REDRIVE_CONFLICT",
+ "EVENT_REDRIVE_EXPIRED",
+ "RECEIPT_CONTEXT_EXPIRED",
+ "EVENT_MAINTENANCE_INCOMPLETE",
+ "UNKNOWN_INTERFACE",
+ "INVALID_CONFIGURATION",
+ "INVALID_PLUGIN_MANIFEST",
+ "INVALID_ATTRIBUTE",
+ "INVALID_PROVIDER_MESSAGE",
+ "UNDECLARED_CAPABILITY",
+ "PLUGIN_ROUTE_ID_CONFLICT",
+ "UNRESOLVED_REFERENCE",
+ "INVALID_RELATIONSHIP",
+ "RELATIONSHIP_CYCLE",
+ "MULTIPLE_PARENTS",
+ "FLOW_VALIDATION_FAILED",
+ "PROVIDER_SYNC_UNSUPPORTED"
+ ],
+ "type": "string"
+ },
+ "family": {
+ "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
+ "enum": [
+ "NOT_FOUND",
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "CONFLICT",
+ "GONE",
+ "PRECONDITION_FAILED",
+ "PRECONDITION_REQUIRED",
+ "PAYLOAD_TOO_LARGE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "UNPROCESSABLE_ENTITY",
+ "LOCKED",
+ "TOO_MANY_REQUESTS",
+ "BAD_GATEWAY",
+ "SERVICE_UNAVAILABLE",
+ "GATEWAY_TIMEOUT",
+ "NOT_IMPLEMENTED",
+ "INTERNAL_SERVER_ERROR",
+ "REQUEST_INVALID",
+ "AUTHENTICATION",
+ "PERMISSION",
+ "ENDPOINT_NOT_FOUND",
+ "ENDPOINT_STATE_CONFLICT",
+ "ENDPOINT_UNAVAILABLE",
+ "RATE_LIMIT",
+ "PROVIDER_BAD_RESPONSE",
+ "PROVIDER_UNAVAILABLE",
+ "PROVIDER_TIMEOUT"
+ ],
+ "type": "string"
+ },
+ "interface": {
+ "description": "Canonical capability interface name the failure applies to, when the failure is interface-specific.",
+ "type": "string"
+ },
+ "message": {
+ "description": "Plain-language description of the failure and the suggested fix.",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.",
+ "type": "string"
+ },
+ "relationshipExternalId": {
+ "description": "Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.",
+ "type": "string"
+ },
+ "status": {
+ "description": "HTTP-equivalent status code of the item failure.",
+ "maximum": 599,
+ "minimum": 400,
+ "type": "integer"
+ },
+ "version": {
+ "description": "Declared capability interface version the failure applies to, when the failure is interface-specific.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "family",
+ "status",
+ "message"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "family": {
+ "description": "The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.",
+ "enum": [
+ "NOT_FOUND",
+ "BAD_REQUEST",
+ "UNAUTHORIZED",
+ "FORBIDDEN",
+ "CONFLICT",
+ "GONE",
+ "PRECONDITION_FAILED",
+ "PRECONDITION_REQUIRED",
+ "PAYLOAD_TOO_LARGE",
+ "UNSUPPORTED_MEDIA_TYPE",
+ "UNPROCESSABLE_ENTITY",
+ "LOCKED",
+ "TOO_MANY_REQUESTS",
+ "BAD_GATEWAY",
+ "SERVICE_UNAVAILABLE",
+ "GATEWAY_TIMEOUT",
+ "NOT_IMPLEMENTED",
+ "INTERNAL_SERVER_ERROR",
+ "REQUEST_INVALID",
+ "AUTHENTICATION",
+ "PERMISSION",
+ "ENDPOINT_NOT_FOUND",
+ "ENDPOINT_STATE_CONFLICT",
+ "ENDPOINT_UNAVAILABLE",
+ "RATE_LIMIT",
+ "PROVIDER_BAD_RESPONSE",
+ "PROVIDER_UNAVAILABLE",
+ "PROVIDER_TIMEOUT"
+ ],
+ "type": "string"
+ },
+ "message": {
+ "description": "Plain-language description of the failure and the suggested next action.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "family",
+ "code",
+ "message"
+ ],
+ "type": "object"
+ }
+]
