This is one of three endpoints in the Agent State API that enables the external changing of agent states. In this call, the Agent is identified by their brand-provided SSO ID (
SSO must be configured and active for this call to work.
You can find a list of defined agent states for the instance using the Retrieve Defined Agent States endpoint. The
id for the desired state returned on that call acts as the
stateUUID query param for this call.
If the agent was already in the target state prior to the call, the server responds with a 200
success, despite processing no change.
In the event that the target isn't in an active session, the server will return a 500 response.
If the call tries to apply a state that the target agent doesn't have access to, the server will issue a 400 response. The response's payload indicates the reason for the failure.