endpoint_manage
endpoint_manageManage the names, types and registry entries of your devices and connected services.
Choose one operation: RENAME, SET_TYPE, SET_ENABLEMENT, MERGE_INTO, or DELETE. Use endpoint_query first and copy the full endpoint ID. Rename and type changes are durable across provider rediscovery. Disabled endpoints stay available for explicit metadata reads, but cannot receive messages; rediscovery preserves the disabled state. DELETE removes the registry entry, though a provider may rediscover it later. MERGE_INTO retains the source endpoint as disabled and moves supported references to the target; it does not create a source-ID alias, and the target's enablement remains in effect. Before MERGE_INTO or DELETE, identify the actual endpoint and explain the effect to the user; never assume two endpoints are duplicates because their names match. This tool changes registry metadata only and never performs physical control.
Required scope
endpoint:writeInput
Fields
Errors
A failed call returns this error object as its result instead.
Fields
- family
stringRequired 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.
Allowed values: 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.
- code
stringRequired 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.
Allowed values: 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_ATTRIBUTE, INVALID_PROVIDER_MESSAGE, UNDECLARED_CAPABILITY, PLUGIN_ROUTE_ID_CONFLICT, UNRESOLVED_REFERENCE, INVALID_RELATIONSHIP, RELATIONSHIP_CYCLE, MULTIPLE_PARENTS, FLOW_VALIDATION_FAILED.
- details
ErrorDetails Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.
- discoveryEndpointId
string 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.
- retryAfterSeconds
integer Suggested retry delay for rate-limit or provider-unavailable failures.
minimum: 0
- providerCode
string The third-party provider's own error code, for support. It is opaque and provider-specific; branch on `code` and `family` instead.
- discoveryEndpointId
- errors
array<SynchronizationItemError> 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.
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.
- pluginRouteId
string Plugin-owned identifier of the rejected route or group route. Set unless the item is a relationship.
- relationshipExternalId
string Plugin-owned `externalId` of the rejected relationship. Set only for relationship items.
- interface
string Canonical capability interface name the failure applies to, when the failure is interface-specific.
- version
string Declared capability interface version the failure applies to, when the failure is interface-specific.
- code
stringRequired 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.
Allowed values: 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_ATTRIBUTE, INVALID_PROVIDER_MESSAGE, UNDECLARED_CAPABILITY, PLUGIN_ROUTE_ID_CONFLICT, UNRESOLVED_REFERENCE, INVALID_RELATIONSHIP, RELATIONSHIP_CYCLE, MULTIPLE_PARENTS, FLOW_VALIDATION_FAILED.
- family
stringRequired 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.
Allowed values: 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.
- pluginRouteId