Ottili AI API — Tool calls

Ottili AI can call platform tools — for example, looking up a customer, drafting a quote, or triggering a Flow. Every tool call is approval-first: the assistant proposes an action, and execution only happens after your approval.

Response shape

When the model wants to call a tool, the response includes tool_calls:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_01J...",
            "type": "function",
            "function": {
              "name": "business_hub.create_quote",
              "arguments": "{\"customer_id\":\"c_123\",\"items\":[{\"sku\":\"SKU1\",\"qty\":2}]}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Approval-first execution

Tool calls that touch the outside world are not executed by the API directly. They are:

1. Returned to your integration as a proposed action.

2. Routed through the approval queue when required by your Settings → AI rules.

3. Executed only after explicit approval; every execution is logged for audit.

This is the same safety model as the in-product assistant. The AI API never silently mutates external systems.

Returning tool results

After the proposed action is approved and executed by your side, continue the conversation by sending the tool result back:

{
  "messages": [
    { "role": "user", "content": "Create a quote for c_123." },
    { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_01J...", "type": "function", "function": { "name": "business_hub.create_quote", "arguments": "{\"customer_id\":\"c_123\"}" } } ] },
    { "role": "tool", "tool_call_id": "call_01J...", "content": "{\"quote_id\":\"q_987\",\"status\":\"draft\"}" }
  ]
}

If a requested tool is unavailable or not entitled for your company, the API returns a clear error rather than fabricating a result.