changedOutput schema / oneOf
Previous value: -[
- {
- "additionalProperties": false,
- "properties": {
- "catalogName": {
- "type": "string"
- },
- "endpointId": {
- "type": "string"
- },
- "expiresAt": {
- "format": "date-time",
- "type": [
- "string",
- "null"
- ]
- },
- "generation": {
- "type": "integer"
- },
- "id": {
- "type": "string"
- },
- "name": {
- "properties": {
- "type": {
- "const": "PLAIN"
- },
- "value": {
- "maxLength": 256,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "type",
- "value"
- ],
- "type": "object"
- },
- "query": {
- "type": "object"
- },
- "reasonCode": {
- "type": "string"
- },
- "revision": {
- "type": "integer"
- },
- "status": {
- "type": "string"
- }
- },
- "required": [
- "id",
- "name",
- "query",
- "endpointId",
- "catalogName",
- "status",
- "generation",
- "revision",
- "expiresAt"
- ],
- "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: +[
+ {
+ "description": "A subscription is a way to listen to events",
+ "properties": {
+ "context": {
+ "additionalProperties": true,
+ "description": "Structured filter criteria for granular device event matching. Keys are dot-notation paths into the message (e.g., \"header.namespace\", \"header.name\"). Values are the expected values to match. All context entries must match for the subscription to fire. Omitting context matches all events.\n",
+ "type": "object"
+ },
+ "etag": {
+ "description": "Opaque strong entity tag of the stored subscription version.",
+ "type": "string"
+ },
+ "eventQueryProfile": {
+ "description": "Supported typed event query validation profile, when this is an event monitor.",
+ "type": "string"
+ },
+ "expiresAt": {
+ "description": "Finite expiration; null means indefinite.",
+ "format": "date-time",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "The unique identifier for the subscription",
+ "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"
+ },
+ "owner": {
+ "description": "The owner of the subscription",
+ "type": "string"
+ },
+ "query": {
+ "description": "Shared Port OS query AST modeled as a recursive JSON graph supporting match, comparison, pattern, freeform, and boolean operators.",
+ "properties": {
+ "and": {
+ "description": "match all fields in the array",
+ "items": {
+ "$ref": "#/$defs/Query"
+ },
+ "type": "array"
+ },
+ "freeformMatch": {
+ "description": "Freeform query string for natural language searches",
+ "type": "string"
+ },
+ "greaterThan": {
+ "allOf": [
+ {
+ "properties": {
+ "key": {
+ "description": "The key to match on",
+ "type": "string"
+ },
+ "value": {
+ "description": "The value to match on",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ ],
+ "description": "Greater than comparison"
+ },
+ "lessThan": {
+ "allOf": [
+ {
+ "properties": {
+ "key": {
+ "description": "The key to match on",
+ "type": "string"
+ },
+ "value": {
+ "description": "The value to match on",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ ],
+ "description": "Less than comparison"
+ },
+ "match": {
+ "allOf": [
+ {
+ "properties": {
+ "key": {
+ "description": "The key to match on",
+ "type": "string"
+ },
+ "value": {
+ "description": "The value to match on",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ ],
+ "description": "Match data between fields"
+ },
+ "not": {
+ "allOf": [
+ {
+ "$ref": "#/$defs/Query"
+ }
+ ],
+ "description": "Negate the inner query (NOT wraps a single child query)"
+ },
+ "or": {
+ "items": {
+ "$ref": "#/$defs/Query"
+ },
+ "type": "array"
+ },
+ "patternMatch": {
+ "description": "Pattern for REGEX queries (e.g., \"*.json\")",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "reasonCode": {
+ "description": "Redacted stable lifecycle reason, when applicable.",
+ "type": "string"
+ },
+ "status": {
+ "description": "Event monitor lifecycle.",
+ "enum": [
+ "ACTIVE",
+ "PAUSED",
+ "SUSPENDED",
+ "EXPIRED",
+ "STOPPED"
+ ],
+ "type": "string"
+ },
+ "target": {
+ "properties": {
+ "cookie": {
+ "additionalProperties": true,
+ "description": "Abstract blob of contextual information necessary to dispatch a message to an endpoint.",
+ "type": "object"
+ },
+ "groupRoutes": {
+ "description": "Group routes Port OS selected for this dispatch, in the order the message requested them (for example the rooms of a clean-room message). Only Port OS sets this field; a value supplied by an API client is discarded.",
+ "items": {
+ "allOf": [
+ {
+ "description": "A group route Port OS resolved for this dispatch. The plugin addresses it by its own pluginRouteId and cookie (the group route's pluginCustomMetadata).",
+ "properties": {
+ "cookie": {
+ "additionalProperties": true,
+ "description": "The group route's pluginCustomMetadata, as reported in discovery.",
+ "type": "object"
+ },
+ "groupId": {
+ "description": "Canonical endpoint group the group route belongs to, after merge redirects.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Typed group-route ID (…/endpoint-group-routes/…).",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "The plugin's own identifier for the group route, as reported in discovery.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "groupId",
+ "pluginRouteId"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "parent": {
+ "description": "A group route Port OS resolved for this dispatch. The plugin addresses it by its own pluginRouteId and cookie (the group route's pluginCustomMetadata).",
+ "properties": {
+ "cookie": {
+ "additionalProperties": true,
+ "description": "The group route's pluginCustomMetadata, as reported in discovery.",
+ "type": "object"
+ },
+ "groupId": {
+ "description": "Canonical endpoint group the group route belongs to, after merge redirects.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Typed group-route ID (…/endpoint-group-routes/…).",
+ "type": "string"
+ },
+ "pluginRouteId": {
+ "description": "The plugin's own identifier for the group route, as reported in discovery.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "groupId",
+ "pluginRouteId"
+ ],
+ "type": "object"
+ }
+ },
+ "type": "object"
+ }
+ ],
+ "description": "A group route selected for this dispatch, for example a room the robot can clean, with its IS_PART_OF parent (for example the room's map) when it has one."
+ },
+ "type": "array"
+ },
+ "id": {
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "ENDPOINT",
+ "PLUGIN",
+ "GROUP",
+ "FLOW",
+ "CONTROL_ROUTE",
+ "MCP_EVENT_BINDING"
+ ],
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "required": [
+ "id",
+ "query",
+ "target",
+ "etag"
+ ],
+ "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"
+ }
+]