API Tools

Reference for call_webhook and mcp_server tool bindings and the secrets their headers use. See Call Your API Mid-Call for when and why.

The Binding

API tools live in the agent's tools array, alongside other tools such as handoff. Get the agent, change the array, and send the whole array back with Update Agent. An update replaces tools, so leaving an entry out deletes it.

{
  "tool_id": "call_webhook",
  "enabled": true,
  "timeout_ms": 6000,
  "side_effect": "read",
  "credential_ref": null,
  "provider_settings": {
    "name": "lookup_reservation",
    "url": "https://api.example.com/reservations",
    "method": "GET",
    "purpose": "When the caller gives a booking reference, look it up before answering.",
    "fields": [
      { "name": "reference", "type": "string", "description": "Booking reference, e.g. HK-2027-118", "required": true }
    ],
    "headers": { "x-api-key": "{{secrets.RESERVATIONS_API_KEY}}" },
    "send_metadata": true,
    "response_fields": ["booking.status", "booking.date"]
  }
}

Field	Rules
provider_settings.name	Lowercase letters, digits, underscores; starts with a letter; 3 to 41 characters; unique per agent
url	Public https host. Private, loopback and plain http hosts are refused
method	GET, POST, PUT or PATCH. GET sends fields as query parameters. Set side_effect to read for GET, write otherwise
fields[].name	Letters, digits, underscores, not starting with a digit. Python keywords and params are reserved
fields[].type	string (default), number, integer, boolean. Optional enum of allowed values
headers	Rymi sets host, content-length, connection and transfer-encoding itself. Credential headers (authorization, x-api-key, api-key, anything containing token or secret) must use {{secrets.NAME}}
timeout_ms	1000 to 10000. Default 6000
send_metadata	Adds call id, agent id and caller phone. Default true
response_fields	Dot paths kept from the JSON response. Default keeps the body, truncated

Node.js

const agent = await rymi.agents.retrieve("3a07...agent");
await rymi.agents.update("3a07...agent", {
  tools: [...agent.tools, lookupReservation], // the binding above
});

Python

agent = rymi.agents.retrieve("3a07...agent")
rymi.agents.update("3a07...agent", tools=agent["tools"] + [lookup_reservation])

The MCP edits one tool by name without resending the array: add_agent_tool, update_agent_tool, remove_agent_tool.

MCP Server Bindings

Each MCP server an agent uses is one mcp_server entry in the same tools array. See Use Your MCP Server.

{
  "tool_id": "mcp_server",
  "enabled": true,
  "timeout_ms": 3000,
  "side_effect": "write",
  "credential_ref": null,
  "provider_settings": {
    "name": "Inventory",
    "url": "https://mcp.example.com/mcp",
    "headers": { "Authorization": "Bearer {{secrets.INVENTORY_MCP_KEY}}" },
    "allowlist": ["check_stock", "reserve_item"]
  }
}

Field	Rules
provider_settings.name	Label shown in Studio. Defaults to the URL's host. The agent sees the server's own tool names
url	The server's streamable-HTTP endpoint. Public https host only; private, loopback and plain http hosts are never connected to
headers	Sent on every request to the server. Values can reference {{secrets.NAME}}, resolved only for the host the secret is pinned to
allowlist	Remote tool names the agent may call, up to 50. Empty means the agent gets nothing from this server, and Rymi doesn't connect to it
enabled	false keeps the server configured but off

At call setup Rymi waits up to 3 seconds per server. A server that is down, slow, or missing a saved secret is skipped and the call goes on without it. A remote tool named like a built-in tool (end_call, knowledge_search) is skipped; built-in tools win.

Tool Secrets

Workspace secrets referenced from headers as {{secrets.NAME}}. Values are encrypted and write-only. Each secret is pinned to one host and only sent there. Publishable keys get 403 on every endpoint below.

List Secrets

GET/v1/tool-secrets

{ "data": [ { "name": "RESERVATIONS_API_KEY", "host": "api.example.com" } ] }

Create or Replace a Secret

PUT/v1/tool-secrets/:name

Field	Type	Required	Description
value	string	Yes	The secret, up to 4,096 characters
host	string	Yes	The public host it may be sent to, e.g. api.example.com

cURL

curl -X PUT https://api.rymi.live/v1/tool-secrets/RESERVATIONS_API_KEY \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk_live_...", "host": "api.example.com" }'

Node.js

await rymi.toolSecrets.set("RESERVATIONS_API_KEY", { value: "sk_live_...", host: "api.example.com" });

Python

rymi.tool_secrets.set("RESERVATIONS_API_KEY", value="sk_live_...", host="api.example.com")

Replacing a secret changes it for every agent that references it.

Delete a Secret

DELETE/v1/tool-secrets/:name

Agents that still reference it fail that header's requests until you save it again.

Test a Request

POST/v1/api-tools/test

Runs one binding once, as the agent would, with sample args. Send { "binding": { ... }, "args": { "reference": "HK-2027-118" } }. Returns { "result": ..., "latency_ms": 412 }.

Discover MCP Tools

POST/v1/mcp-servers/discover

Lists the tools an MCP server offers, so you can pick its allowlist. Rymi connects the way a call does: the same handshake, the same headers with secrets filled in, redirects refused. It gives up after 8 seconds.

Field	Type	Required	Description
url	string	Yes	Public https URL of the server
headers	object	No	Header values, which may reference {{secrets.NAME}}

curl -X POST https://api.rymi.live/v1/mcp-servers/discover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer {{secrets.INVENTORY_MCP_KEY}}" } }'

{ "data": [ { "name": "check_stock", "description": "Stock level for a SKU" } ] }

Errors

Status	Meaning
400	Secret name not UPPER_SNAKE_CASE (2 to 64 characters), value missing or over 4,096 characters, no public host, (test) a binding without a valid name and URL, (discover) a URL that isn't public https, or missing_secrets the headers reference
403	Publishable keys can't use these endpoints
502	(discover) The MCP server didn't answer, refused the request, or redirected