Endpoint Simulators
Endpoint Simulators lets customers simulate endpoints to test out their flows and integrations.
Use endpoint simulators whenever you want to make sure that things work before you buy real devices.
For example, if a customer wants to control a lightbulb and make sure that it will work with Port OS's lightbulb integration, they can use an endpoint simulator for a lightbulb to see how the experience looks.
/endpoint-simulatorsCreates a new endpoint simulator or updates an existing one. When an id is provided in the request body, the simulator with that ID is updated. When no id is provided, a new simulator is created along with its associated endpoint, auth link, and route.
Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
Required scope
Any authenticated access token
Header parameters
- Idempotency-Key
stringRequired Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.
minLength: 1
maxLength: 255
- If-Match
string Required for a full replacement when the request identifies an existing resource. Send that resource's quoted strong etag from its last GET. A missing condition on a replacement returns 428 PRECONDITION_REQUIRED; a stale condition returns 412 PRECONDITION_FAILED. Omit this header when creating a new resource without an id. Wildcards are accepted only where the operation explicitly permits them.
minLength: 1
Request body
Fields
- id
string Existing simulator ID to replace; omitted on create. An unknown ID returns 404.
pattern: "^port1/[^/]+/[^/]+/endpoint-simulators/[^/]+$"
- device_type
stringRequired The type of device being simulated
Allowed values
LIGHTLOCKSENSORTHERMOSTATTELEVISIONCAMERAVACUUMCOLORED_LIGHTSWITCHPLUGFANCLOSUREWINDOW_COVERINGCONTACT_SENSORHUMIDITY_SENSORLIGHT_SENSORSTANDALONE_TEMPERATURE_SENSORAIR_QUALITY_SENSORCO_SENSORCOOKTOPDISHWASHERMICROWAVE_OVENOVENREFRIGERATOREXTRACTOR_HOODLAUNDRY_WASHERLAUNDRY_DRYERAUDIO_PLAYERMEDIA_PLAYERMEDIA_PROVIDERSPEAKERTEXT_MESSAGE_RECEIVERCALENDAR_PROVIDERKEYPADLOCATION_TRACKERSMOKE_ALARMSECURITY_PANELPET_FEEDERFILESYSTEMLIGHTING_HUB
- configuration
SimulatorConfiguration Typed simulator producer settings. Omitted camera profile advertises motion/person; doorbell adds chime. Profile must be compatible with device_type. Rooms are valid only for a VACUUM or LIGHTING_HUB simulator; an omitted list gives a vacuum Living room, Kitchen, Bedroom and Hallway; a LIGHTING_HUB must list them.
Errors
400 IDEMPOTENCY_KEY_REQUIREDInvalid request payload
Check the request fields and any validation details, then correct the payload.
401 UNAUTHORIZEDUnauthorized - invalid or missing authentication token
Obtain a valid access token, then retry.
403 FORBIDDENForbidden - insufficient permissions
Check the linked account and its permissions for the device or resource.
404 NOT_FOUNDThe named simulator does not exist.
Verify the target identifier and that its endpoint or plugin route still exists.
409 IDEMPOTENCY_KEY_IN_FLIGHTIdempotency key in flight.
Check the device’s current mode or state. Retry only after the conflict is resolved.
412 PRECONDITION_FAILEDStale If-Match.
Inspect the returned code and family and follow the error handling guide.
415 UNSUPPORTED_MEDIA_TYPEUnsupported request media type.
Inspect the returned code and family and follow the error handling guide.
422 IDEMPOTENCY_KEY_REUSEDIdempotency key payload conflict.
Correct the rejected value using the constraints in the error details or request schema.
428 PRECONDITION_REQUIREDMissing If-Match on replace.
Inspect the returned code and family and follow the error handling guide.
500 INTERNALInternal server error
Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.
/endpoint-simulatorsLists endpoint simulators for the authenticated user. Supports pagination via maxResults and nextToken query parameters. When owner is not specified, defaults to the authenticated caller.
Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
Required scope
Any authenticated access token
Query parameters
Returns
200
Simulators retrieved successfully
Fields
- results
array<Simulator>Required List of simulators
An endpoint simulator.
- etag
stringRequired Strong version of simulator name, device type and configuration. Observed state does not advance this version.
- state
object Current observed simulated-device state. Updated by the simulator provider, independently of the writable configuration version.
- id
stringRequired The unique identifier for the simulator
pattern: "^port1/[^/]+/[^/]+/endpoint-simulators/[^/]+$"
- device_type
stringRequired The type of device being simulated
Allowed values
LIGHTLOCKSENSORTHERMOSTATTELEVISIONCAMERAVACUUMCOLORED_LIGHTSWITCHPLUGFANCLOSUREWINDOW_COVERINGCONTACT_SENSORHUMIDITY_SENSORLIGHT_SENSORSTANDALONE_TEMPERATURE_SENSORAIR_QUALITY_SENSORCO_SENSORCOOKTOPDISHWASHERMICROWAVE_OVENOVENREFRIGERATOREXTRACTOR_HOODLAUNDRY_WASHERLAUNDRY_DRYERAUDIO_PLAYERMEDIA_PLAYERMEDIA_PROVIDERSPEAKERTEXT_MESSAGE_RECEIVERCALENDAR_PROVIDERKEYPADLOCATION_TRACKERSMOKE_ALARMSECURITY_PANELPET_FEEDERFILESYSTEMLIGHTING_HUB
- configuration
SimulatorConfiguration Typed simulator producer settings. Omitted camera profile advertises motion/person; doorbell adds chime. Profile must be compatible with device_type. Rooms are valid only for a VACUUM or LIGHTING_HUB simulator; an omitted list gives a vacuum Living room, Kitchen, Bedroom and Hallway; a LIGHTING_HUB must list them.
- etag
- errors
array<Error> Partial query errors collected while returning available results.
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.
- 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_FOUNDBAD_REQUESTUNAUTHORIZEDFORBIDDENCONFLICTGONEPRECONDITION_FAILEDPRECONDITION_REQUIREDPAYLOAD_TOO_LARGEUNSUPPORTED_MEDIA_TYPEUNPROCESSABLE_ENTITYLOCKEDTOO_MANY_REQUESTSBAD_GATEWAYSERVICE_UNAVAILABLEGATEWAY_TIMEOUTNOT_IMPLEMENTEDINTERNAL_SERVER_ERRORREQUEST_INVALIDAUTHENTICATIONPERMISSIONENDPOINT_NOT_FOUNDENDPOINT_STATE_CONFLICTENDPOINT_UNAVAILABLERATE_LIMITPROVIDER_BAD_RESPONSEPROVIDER_UNAVAILABLEPROVIDER_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_REQUESTUNAUTHORIZEDFORBIDDENINSUFFICIENT_SCOPENOT_FOUNDCONFLICTUNPROCESSABLE_ENTITYUNSUPPORTED_OPERATIONTOO_MANY_REQUESTSSERVICE_UNAVAILABLENOT_IMPLEMENTEDINTERNALCHECKSUM_MISMATCHFILE_TOO_LARGESTORAGE_UNAVAILABLEINSUFFICIENT_PERMISSIONSINVALID_FILE_TYPEQUOTA_EXCEEDEDCONCURRENT_MODIFICATIONENDPOINT_UNREACHABLEBRIDGE_UNREACHABLECLOUD_CONTROL_DISABLEDENDPOINT_BUSYENDPOINT_LOW_POWERAUTHORIZATION_CREDENTIAL_INVALIDAUTHORIZATION_CREDENTIAL_EXPIREDINVALID_DIRECTIVEINVALID_VALUEVALUE_OUT_OF_RANGENOT_SUPPORTED_IN_CURRENT_MODERATE_LIMIT_EXCEEDEDPROVIDER_SERVICE_UNAVAILABLEPROVIDER_TIMEOUTPROVIDER_INTERNAL_ERRORINVALID_PROVIDER_RESPONSEOUTCOME_UNKNOWNPRECONDITION_FAILEDAUTH_LINK_NOT_READYAUTH_LINK_NOT_DISCONNECTABLEPRECONDITION_REQUIREDIDEMPOTENCY_KEY_REQUIREDIDEMPOTENCY_KEY_REUSEDIDEMPOTENCY_KEY_IN_FLIGHTIDEMPOTENCY_KEY_INVALIDGROUP_MERGEDMULTI_ROOM_UNSUPPORTEDMAP_NOT_ACTIVETARGET_UNSUPPORTEDTARGET_AMBIGUOUSTARGET_GROUP_NOT_FOUNDTARGET_GROUP_DISABLEDDUPLICATE_TARGET_GROUPMESSAGE_UNSUPPORTEDMESSAGE_AMBIGUOUSENDPOINT_DISABLEDENDPOINT_ROUTE_CHANGEDENDPOINT_HAS_DEPENDENCIESENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVEENDPOINT_COMMITTED_CLEANUP_PENDINGDEEP_QUERY_FAILEDPROVIDER_NO_STATEEVENT_MANAGEMENT_DISABLEDSUBSCRIPTION_IDENTITY_IMMUTABLEUNSUPPORTED_MEDIA_TYPEEVENT_PAYLOAD_TOO_LARGEREQUEST_BODY_TOO_LARGEEVENT_IDENTITY_CONFLICTEVENT_INGRESS_QUOTA_EXCEEDEDEVENT_RECEIPT_EXPIREDEVENT_STORAGE_UNAVAILABLEEVENT_DEAD_LETTER_NOT_FOUNDEVENT_REDRIVE_CONFLICTEVENT_REDRIVE_EXPIREDRECEIPT_CONTEXT_EXPIREDEVENT_MAINTENANCE_INCOMPLETEUNKNOWN_INTERFACEINVALID_CONFIGURATIONINVALID_PLUGIN_MANIFESTINVALID_ATTRIBUTEINVALID_PROVIDER_MESSAGEUNDECLARED_CAPABILITYPLUGIN_ROUTE_ID_CONFLICTUNRESOLVED_REFERENCEINVALID_RELATIONSHIPRELATIONSHIP_CYCLEMULTIPLE_PARENTSFLOW_VALIDATION_FAILEDPROVIDER_SYNC_UNSUPPORTED
- 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.
- 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_REQUESTUNAUTHORIZEDFORBIDDENINSUFFICIENT_SCOPENOT_FOUNDCONFLICTUNPROCESSABLE_ENTITYUNSUPPORTED_OPERATIONTOO_MANY_REQUESTSSERVICE_UNAVAILABLENOT_IMPLEMENTEDINTERNALCHECKSUM_MISMATCHFILE_TOO_LARGESTORAGE_UNAVAILABLEINSUFFICIENT_PERMISSIONSINVALID_FILE_TYPEQUOTA_EXCEEDEDCONCURRENT_MODIFICATIONENDPOINT_UNREACHABLEBRIDGE_UNREACHABLECLOUD_CONTROL_DISABLEDENDPOINT_BUSYENDPOINT_LOW_POWERAUTHORIZATION_CREDENTIAL_INVALIDAUTHORIZATION_CREDENTIAL_EXPIREDINVALID_DIRECTIVEINVALID_VALUEVALUE_OUT_OF_RANGENOT_SUPPORTED_IN_CURRENT_MODERATE_LIMIT_EXCEEDEDPROVIDER_SERVICE_UNAVAILABLEPROVIDER_TIMEOUTPROVIDER_INTERNAL_ERRORINVALID_PROVIDER_RESPONSEOUTCOME_UNKNOWNPRECONDITION_FAILEDAUTH_LINK_NOT_READYAUTH_LINK_NOT_DISCONNECTABLEPRECONDITION_REQUIREDIDEMPOTENCY_KEY_REQUIREDIDEMPOTENCY_KEY_REUSEDIDEMPOTENCY_KEY_IN_FLIGHTIDEMPOTENCY_KEY_INVALIDGROUP_MERGEDMULTI_ROOM_UNSUPPORTEDMAP_NOT_ACTIVETARGET_UNSUPPORTEDTARGET_AMBIGUOUSTARGET_GROUP_NOT_FOUNDTARGET_GROUP_DISABLEDDUPLICATE_TARGET_GROUPMESSAGE_UNSUPPORTEDMESSAGE_AMBIGUOUSENDPOINT_DISABLEDENDPOINT_ROUTE_CHANGEDENDPOINT_HAS_DEPENDENCIESENDPOINT_EVENT_SUBSCRIPTIONS_ACTIVEENDPOINT_COMMITTED_CLEANUP_PENDINGDEEP_QUERY_FAILEDPROVIDER_NO_STATEEVENT_MANAGEMENT_DISABLEDSUBSCRIPTION_IDENTITY_IMMUTABLEUNSUPPORTED_MEDIA_TYPEEVENT_PAYLOAD_TOO_LARGEREQUEST_BODY_TOO_LARGEEVENT_IDENTITY_CONFLICTEVENT_INGRESS_QUOTA_EXCEEDEDEVENT_RECEIPT_EXPIREDEVENT_STORAGE_UNAVAILABLEEVENT_DEAD_LETTER_NOT_FOUNDEVENT_REDRIVE_CONFLICTEVENT_REDRIVE_EXPIREDRECEIPT_CONTEXT_EXPIREDEVENT_MAINTENANCE_INCOMPLETEUNKNOWN_INTERFACEINVALID_CONFIGURATIONINVALID_PLUGIN_MANIFESTINVALID_ATTRIBUTEINVALID_PROVIDER_MESSAGEUNDECLARED_CAPABILITYPLUGIN_ROUTE_ID_CONFLICTUNRESOLVED_REFERENCEINVALID_RELATIONSHIPRELATIONSHIP_CYCLEMULTIPLE_PARENTSFLOW_VALIDATION_FAILEDPROVIDER_SYNC_UNSUPPORTED
- 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_FOUNDBAD_REQUESTUNAUTHORIZEDFORBIDDENCONFLICTGONEPRECONDITION_FAILEDPRECONDITION_REQUIREDPAYLOAD_TOO_LARGEUNSUPPORTED_MEDIA_TYPEUNPROCESSABLE_ENTITYLOCKEDTOO_MANY_REQUESTSBAD_GATEWAYSERVICE_UNAVAILABLEGATEWAY_TIMEOUTNOT_IMPLEMENTEDINTERNAL_SERVER_ERRORREQUEST_INVALIDAUTHENTICATIONPERMISSIONENDPOINT_NOT_FOUNDENDPOINT_STATE_CONFLICTENDPOINT_UNAVAILABLERATE_LIMITPROVIDER_BAD_RESPONSEPROVIDER_UNAVAILABLEPROVIDER_TIMEOUT
- pluginRouteId
- family
Errors
400 BAD_REQUESTInvalid request parameters
Check the request fields and any validation details, then correct the payload.
401 UNAUTHORIZEDUnauthorized - invalid or missing authentication token
Obtain a valid access token, then retry.
403 FORBIDDENForbidden - insufficient permissions
Check the linked account and its permissions for the device or resource.
500 INTERNALInternal server error
Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.
/endpoint-simulators/{id}Read one simulator with its persisted writable-document etag and observed associations.
Required scope
Any authenticated access token
Path parameters
- id
stringRequired URL-encoded complete simulator identifier. A retained legacy identifier addresses only its exact stored simulator row.
pattern: "^(?:port1/[a-z][a-z0-9]*(?:-[a-z0-9]+)*/[A-Za-z0-9][A-Za-z0-9._@+=:~-]{0,254}/endpoint-simulators/[A-Za-z0-9][A-Za-z0-9._@+=:~-]{0,254}|port1\\.simulator\\.[A-Za-z0-9][A-Za-z0-9._@+=:~-]{0,254})$"
Errors
404 NOT_FOUNDSimulator not found.
Verify the target identifier and that its endpoint or plugin route still exists.
/endpoint-simulators/{id}Deletes the simulator and its associations atomically. Receipts are retained for 24 hours.
Required scope
Any authenticated access token
Path parameters
- id
stringRequired URL-encoded complete simulator identifier. A retained legacy identifier addresses only its exact stored simulator row.
pattern: "^(?:port1/[a-z][a-z0-9]*(?:-[a-z0-9]+)*/[A-Za-z0-9][A-Za-z0-9._@+=:~-]{0,254}/endpoint-simulators/[A-Za-z0-9][A-Za-z0-9._@+=:~-]{0,254}|port1\\.simulator\\.[A-Za-z0-9][A-Za-z0-9._@+=:~-]{0,254})$"
Header parameters
- Idempotency-Key
stringRequired Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.
minLength: 1
maxLength: 255
- If-Match
stringRequired The quoted strong entity tag of the resource the client last read (its `etag` field or `ETag` response header). The mutation is applied only when it still matches: a stale value returns 412 PRECONDITION_FAILED and a missing header returns 428 PRECONDITION_REQUIRED. Wildcards are accepted only where the operation explicitly permits them.
minLength: 1
Returns
200
Simulator deleted.
No response body.
Errors
400 IDEMPOTENCY_KEY_REQUIREDMissing or invalid key, or a DELETE body was supplied.
Check the request fields and any validation details, then correct the payload.
404 NOT_FOUNDSimulator not found.
Verify the target identifier and that its endpoint or plugin route still exists.
409 IDEMPOTENCY_KEY_IN_FLIGHTIdempotency key in flight.
Check the device’s current mode or state. Retry only after the conflict is resolved.
412 PRECONDITION_FAILEDStale If-Match.
Inspect the returned code and family and follow the error handling guide.
422 IDEMPOTENCY_KEY_REUSEDIdempotency key payload conflict.
Correct the rejected value using the constraints in the error details or request schema.
428 PRECONDITION_REQUIREDMissing If-Match.
Inspect the returned code and family and follow the error handling guide.