Skip to main content
GET
Get inbound router
The inbound router lets an agent choose which of its tasks answers a new inbound conversation, using your rules and what the lead writes. In the app this is Let your agent choose the task. See Tasks that work together. In the API an agent is a master_workflow and a task is a workflow. The agent ID goes in the path, and tasks appear in fields such as default_workflow_id and target_workflow_id.

How the router picks a task

For each new conversation, the router goes through these steps in order and stops at the first one that decides. Each step has a layer value, shown in List decisions. If something fails along the way, the conversation goes to the default task so the lead still gets an answer (error_fail_open).

Before you start

  • The inbound router is not available on every account. Without it, every endpoint in this section returns 403 inbound_router_not_enabled.
  • MCP keys need workflows:read to read and workflows:write to make changes. Full-access API keys need nothing else.
  • Every change requires "confirm": true in the body. Without it, the API returns 400 confirmation_required and changes nothing.
  • Errors return a stable code in error, such as agent_group_not_found. Map the code to your own message.
  • To choose which numbers and inboxes reach the agent, see List entry points.

Authorizations

X-API-Key
string
header
required

API key for authentication. Keys are prefixed with nxr_live_.

Path Parameters

id
string<uuid>
required

Agent ID (master_workflow in the API). A malformed ID returns 400 invalid_group_id.

Response

Router of the agent.

agent_group_id
string<uuid>
required

Agent ID.

settings
object | null
required

Router settings of the agent. null when the router was never configured for it.

identity
object | null
required

The agent's shared identity: the name, voice, language, and instructions all of its tasks speak with, including while the agent works out which task should answer. When the agent has no complete identity of its own, the values shown come from the default task.

tasks
object[]
required

Tasks of the agent.

Last modified on September 28, 2026