Operations
Operations

Set tool headers

FULL-REPLACE an HTTP tool's headers map (this is NOT a merge: the new map overwrites the existing one entirely, so always send the COMPLETE set of headers you want, not just the ones that changed). Identify the tool by toolName (its snake_case name) or toolId. Pass an object of `{ headerName: value }` (NOT array-of-{key,value}). Empty object clears all headers. Values may contain `{{variable_name}}` placeholders, commonly `Authorization: Bearer {{api_key}}`. **Never send a real credential as a header value**: headers are stored on the tool row in the clear, and a literal credential is refused wherever it is recognisable. Send the placeholder, then put the value in the Vault with `request_secret_variable` in the app (the operator types it into a dialog you never see) or, over the MCP, `set_secret_variable`.

POST
/operations/set_tool_headers

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Header Parameters

Idempotency-Key?string

A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/operations/set_tool_headers" \  -H "Content-Type: application/json" \  -d '{    "headers": {      "property1": "string",      "property2": "string"    },    "agent": "string"  }'
{}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}

Set tool follow-up POST

Decide what happens when a call ends before this tool fires, the caller hangs up mid-enquiry and the action the agent was working toward is lost. `off` (default) loses it, as today. `notify` has a post-call judge read the call and alert someone with what the agent was about to do. `complete` runs the tool after the call through a headless agent-run, using only what the caller actually said, then reports that it ran. `complete` is refused on tools that need the live call (transfer_to_human, end_call, the live-screen set) or that message the CALLER rather than the business (send_text_message), use `notify` for those. Set `requiredArgs` so a half-finished call downgrades to notify instead of guessing a phone number, and `note` to tell the judge when NOT to act (cold callers, robocalls). Identify the tool by toolName or toolId.

Set tool mock POST

Configure mock mode on an HTTP tool. Identify the tool by toolName (its snake_case name) or toolId. Mock mode lets the tool return a canned response, `mockResponse`, after `mockDelayMs`, instead of calling its real URL, so an agent can be tested before its API exists and without firing real side effects. Mocks are scoped to test surfaces: on a phone call carrying a real caller the runtime refuses to serve the canned body and returns an error envelope instead, so never leave a mock on as a substitute for a working endpoint. Pass only the fields you want to change; omit the rest. Builtin tools can't be mocked. To 'edit the mock response', send `mockResponse` with the new JSON string. A mock body may echo the call's own arguments with `{{args.field}}`, write `{"category": "{{args.category}}"}` rather than a fixed value for anything the real API would reflect back, or the mock will contradict what the agent sent and a judge will fail the run for it. TIME THIS EDIT: a mock lives on the agent's DRAFT, so changing one starts a new version and every test green on the old one goes stale (get_test_results marks them). Do it at the start of a draft cycle, not while re-greening a suite you are about to publish. To make a mocked verify_* tool reject a wrong identifier, send `mockMatch`, a JSON string of {arg: expected-value} pairs the call must match (a value can nest an object or array for a tool whose argument is itself structured). To mock a tool that returns DIFFERENT data for different inputs (order A → record A, order B → record B, else → not found), send `mockMocks`, a JSON string of [{match, response, delayMs?}, …]; it supersedes the single mock when set.