Check whether an agent is reachable in a workspace
GET /api/agent-definitions/{id}/reachability
Whether the assistant hands tasks to the agent in a workspace, and if not, why: the verdict check_agent_reachability gives over the tenant MCP. The answer reflects the agent’s current configuration; the assistant applies a change within five minutes. Requires the agents:read scope; a key restricted to a brand or workspace checks a workspace inside its restriction.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The agent.
Query Parameters
Section titled “Query Parameters ”The workspace to check the agent in.
Responses
Section titled “ Responses ”The verdict.
object
The agent.
The workspace checked.
custom for an agent created in the account, platform for one oHallo provides.
Whether the assistant hands matching tasks to the agent in this workspace.
Why it does not; empty when reachable is true. no_mcp_connections: the agent has no connection. mcp_connection_unavailable: the connections in connectionIds do not serve this workspace, each scoped to another workspace or brand, inactive, or removed; a connection serves a workspace when it is scoped to the workspace, its brand or the whole account. required_capability_unavailable: no active connection in the workspace offers what an agent oHallo provides needs. not_a_specialist and excluded_from_registry: an agent oHallo provides that the assistant does not hand tasks to.
object
With mcp_connection_unavailable: the connections that do not serve the workspace.
With required_capability_unavailable: what the agent needs.
Example
[ { "code": "mcp_connection_unavailable", "connectionIds": [ "c3d4e5f6-7890-4abc-8ef0-1234567890ab" ] }]The request carries no valid credential.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]An API key without the agents:read scope receives the scopes it lacks in missing_scopes.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]No such agent, or no such workspace; a workspace outside the API key’s brand or workspace restriction answers 404 as well.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]workspaceId is missing or is not a UUID.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]The check could not be made; retry the request.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]