Route a request to a declared tool

POST /v1/task with task: "route" evaluates a question against the tools you provide. A decided result identifies a tool and bound arguments. An ask result identifies required information that is missing; unresolved and refused mean the application should not dispatch a tool call. The calling application remains responsible for authorization and execution.

Request

{
  "task": "route",
  "question": "show my payslip",
  "tools": [
    {
      "name": "payroll",
      "description": "Show the employee's own payroll: salary, payslips, deductions and payment dates.",
      "parameters": {"type": "object", "properties": {}}
    },
    {
      "name": "assets",
      "description": "Show the equipment assigned to the employee: laptop, monitor, phone.",
      "parameters": {"type": "object", "properties": {}}
    }
  ],
  "tiers": ["t1"]
}

Send it to your configured engine:

curl -sS http://127.0.0.1:8700/v1/task \
  -H 'Content-Type: application/json' \
  -d @route.json

Handle the result

Check outcome and may_act before dispatch. For decided, pass the returned tool name and arguments through your application's own permission checks. Do not execute on ask, unresolved, or refused.

{
  "outcome": "decided",
  "may_act": true,
  "tool_call": {"name": "payroll", "arguments": {}, "select": []},
  "evidence": {"tool": [], "arguments": {}}
}

This example shows the captured route response shape. It is not a statement about latency, tool authorization, or the correctness of an external action. See the JavaScript SDK guide for the typed route method and the OpenAI wire reference for the compatible chat-completions endpoint.