X-API-Key header. They only see agents and simulations in the workspaces your key can access.
Turn mocking on or off
PUT https://api.getbluejay.ai/v1/agents/{agent_id}/mock-tools
Needs write access to the agent’s workspace.
Each tool setting:
For ElevenLabs agents, turning it on creates the
bluejay-mocks branch, or reuses it when mocking is already on, and turning it off archives the branch and deletes its tool copies. A 400 means the ElevenLabs agent has no versions, so turn on versioning in ElevenLabs first. A 502 means a call to the ElevenLabs API failed, and mocking stays as it was. Queuing a voice run also updates the branch to match the live agent and its tools. If that update fails, the run is not queued and the queue request answers 502.
The MCP tool is set_agent_mock_tools, with agent_id and enabled. It returns the same fields.
Set one tool
PUT https://api.getbluejay.ai/v1/agents/{agent_id}/mock-tools/{tool_name}
The body is one tool setting, such as {"mode": "fixed", "response": {"slots": []}}. It also turns mocking on for the agent, and returns the same fields as above. The MCP tool is set_agent_tool_mock.
Order
For each tool call in a simulation, Bluejay uses the first of:- The Digital Human’s
tool_responsesentry for the tool. - The agent’s
fixedresponse for the tool. - A generated result, unless the tool is set to
real. - Your real tool. On Google CES and Dialogflow CX, a tool set to
realgets an error result instead, since nothing can run your real tool on that path.
Resolve a mock
POST https://api.getbluejay.ai/v1/tool-mocks/resolve
Call it from your tool server before you run the real tool.
When the call is a Bluejay simulation and Bluejay can’t produce a result, the answer is
mocked: true with the result {"error": "This tool is unavailable in this test."}.
caller_number matches the Digital Human with that number whose conversation is running now. If none is running, the answer is mocked: false.
An unknown id, an id from another organization, and an id from a workspace your key can’t read all answer mocked: false. Bluejay never reveals whether the id exists.
The limit is 600 requests per minute per organization. Over it, the endpoint answers 429. Treat a 429 like any other error: return an error result when the call has a test id, otherwise run the real tool.
SDK helper
The helpers are inbluejay.helpers.tool_mocks in the bluejay-sdk Python package.
The helper fails closed on tests:
- A call with no test id and no caller number never contacts Bluejay.
- With a test id, a lookup that fails, times out, or answers 429 returns
{"error": "This tool is unavailable in this test."}. Your real tool never runs. - With only a caller number, the call may be a real caller, so a failed lookup runs your real tool.
- A mocked result is returned as a string. Objects are JSON-encoded.
Which calls reach your real tool
Generated results usually take a second or two. If generation fails, the tool gets an error result on every platform, and your real tool does not run.
On ElevenLabs, every tool call in the simulation goes to Bluejay, so calls the agent makes early or drops after an interruption never reach your real tool. With the resolver, every call that your handler checks first gets the mock in the same way.