Docs

Appearance

Call Your API Mid-Call ​

An API tool lets your agent call your own HTTPS endpoint while it talks: look up a booking, check stock, create a ticket. You describe the endpoint and the fields the agent fills in; the agent decides when to call it from your instructions, then speaks from the response.

An agent can have any number of API tools, each with its own name. In Studio they live under Tools → API requests. Through the API they're call_webhook entries in the agent's tools array; through the MCP you edit them by name.

Add one ​

  1. Open Tools → API requests and add a request. In Name, enter the name the agent calls, such as lookup_reservation.
  2. Enter the Endpoint URL (public https only) and the Method. GET sends the fields as query parameters; POST, PUT and PATCH send a JSON body. Tick This tool only reads data for lookups. The agent confirms with the caller before a send.
  3. Fill in When should the agent call this? "When the caller gives a booking reference, look it up before answering." Leave it empty and the agent rarely calls the tool.
  4. Add the fields the agent fills in, each with a type (string, number, integer, boolean), a short description, whether it's required, and optional fixed values.
  5. Add headers. Put credentials in a secret, never in the header value.
  6. Click Test request to run it once with sample values, then save. The live agent uses it from its next call.

Rymi adds the call id, agent id and caller phone to each request unless you turn off Include call details. Timeout (seconds) defaults to 6 and takes 1 to 10. To keep the agent's context small, list what it needs under Return only these fields as dot paths, such as booking.status.

Keep keys in secrets ​

A header named Authorization, x-api-key, api-key, or containing token or secret, must hold a reference like {{secrets.RESERVATIONS_API_KEY}}, not the key itself. Save the value once as a workspace secret, pinned to one host:

  • Rymi encrypts the value and never returns it.
  • Rymi only sends it to the host you pinned, so a tool pointed elsewhere can't leak it.
  • Replacing a secret updates every agent that references it.

Secret names are UPPER_SNAKE_CASE, 2 to 64 characters.

Through the API, SDK or MCP ​

  • MCP: list_agent_tools, add_agent_tool, update_agent_tool, remove_agent_tool, list_tool_secrets, set_tool_secret. The MCP checks each tool the way Studio does and refuses a literal key in a credential header.
  • API and SDKs: see API Tools. Read the agent first and send back its whole tools array, so you don't drop its other tools.

Already run an MCP server? Use its tools instead of describing each endpoint here.