Custom API tools

Custom API tools let your agent reach into your systems mid-call. The agent collects the details it needs from the caller, calls an HTTPS endpoint you control, and uses the response to answer — so it can look up an order, check stock, fetch a balance, or anything your API can return.

Add a custom tool

Open an agent (Agents → your agent) and scroll to Call actions → Custom API tools → Add custom tool. For each tool you provide:

• Name — the function name the agent uses internally, lowercase with underscores (e.g. lookup_order).
• When should the agent use it? — a clear description so the model knows when to call it (e.g. "Look up the status of a customer's order by its number.").
• Method — GET or POST.
• Endpoint URL — your HTTPS endpoint (e.g. https://api.yourbusiness.com/orders).
• Authorization header (optional) — sent as the Authorization header, e.g. Bearer your_api_key.
• Parameters — the values the agent should collect from the caller and pass to your endpoint. Each has a name, a short description, and whether it's required.

How it works during a call

1. The agent decides the tool is relevant (based on your description) and collects the parameters from the caller.
2. SunoVoice calls your endpoint:
   • GET → parameters are sent as query string values.
   • POST → parameters are sent as a JSON body.
   • Your Authorization header (if set) is included.
3. Your endpoint's response (text or JSON) is handed back to the agent, which uses it to answer the caller.

Example

A tool named lookup_order (GET, https://api.yourbusiness.com/orders) with one required parameter order_number:

Caller: "Can you check on order 10432?"
→ Agent calls GET https://api.yourbusiness.com/orders?order_number=10432
→ Your API returns: {"status":"shipped","eta":"Tuesday"}
Agent: "Order 10432 has shipped and should arrive Tuesday."

Building your endpoint

• Return something short and clear. The agent speaks from your response, so a concise JSON object or sentence works best. Keep it small — long responses are truncated.
• Respond quickly. Calls time out after ~10 seconds; aim for well under that so the caller isn't left waiting.
• Handle errors gracefully. If you return an error status, the agent tells the caller it couldn't retrieve the info rather than guessing.
• Secure it. Use the Authorization header to authenticate requests as coming from your agent.

Security & limits

• HTTPS only. Plain http:// URLs are rejected.
• Public endpoints only. Requests to private, internal, or loopback addresses (and cloud metadata endpoints) are blocked, and redirects are not followed.
• Only your declared parameters are sent — nothing else from the call.
• Reasonable caps apply (number of tools, parameters, response size, timeout).

Tips

• Name and describe tools the way you'd brief a new employee — the clearer the description, the better the agent knows when to use it.
• Keep GET tools read-only and idempotent (lookups), since the agent may call them more than once.
• Test it with a browser or phone test call and watch your endpoint's logs.

Frequently asked questions

Can the agent send data to my system, not just read? Yes — use POST and your endpoint receives the parameters as a JSON body. Just make sure repeated calls are safe.

Can I require an API key? Yes — put it in the Authorization header field (e.g. Bearer …); it's sent with every call to your endpoint.

What if my endpoint is down? The agent is told it couldn't retrieve the information and continues the call — it won't crash or hang.

Next step

Prefer to drive SunoVoice from your side instead? See API configuration and webhooks.