Create a tool

POST

https://example.ada.support/api/v2/tools/

POST

/api/v2/tools/

import requests
url = "https://example.ada.support/api/v2/tools/"
payload = {
    "type": "api",
    "name": "get_order_status",
    "description": "Look up the status of a customer's order.",
    "api": {
        "url": "https://api.example.com/orders/{var:order_id}",
        "request": {
            "method": "GET",
            "content_type": "json"
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "507f1f77bcf86cd799439011",
  "type": "api",
  "name": "get_order_status",
  "description": "Look up the status of a customer's order.",
  "inputs": [],
  "outputs": [],
  "enabled": true,
  "direct_use": true,
  "availability_rules": null,
  "api": {
    "url": "https://api.example.com/orders/{var:order_id}",
    "request": {
      "method": "GET",
      "content_type": "json",
      "body": "",
      "headers": []
    }
  }
}

Creates an api or code tool.

The body is the Tool envelope without id or read-only fields (inputs[].required). Request body / headers and code environment are optional. availability_rules is the structured Knowledge rule object, never the internal DSL string. Authorization headers on api tools are stored but stripped on every read. A code.environment row with source=sensitive_value is write-only: create stores the submitted value (empty means an empty secret). A GET-then-POST clone does not copy the stored secret. Send it again.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

typeenumRequired

Allowed values:

namestringRequired

descriptionstringRequired

inputslist of objectsOptional

outputslist of objectsOptional

enabledbooleanOptionalDefaults to true

direct_useboolean or nullOptional

availability_rulesobject or nullOptional

A two-level tree of conditions that determines availability based on variable values during a conversation. The root group has a match combinator and a list of conditions or condition groups. A rule may contain at most 1000 conditions in total, counting every condition across the root and all nested condition groups.

apiobjectOptional

How an api tool calls its HTTP endpoint, on create

codeobjectOptional

The sandboxed Python a code tool runs, on create

Response

The created tool

idstring

The tool's id

typeenum

Which kind of tool this is, and which implementation key is present

Allowed values:

namestring

The tool's name, as the model sees it

descriptionstring

What the tool does, as the model sees it

inputslist of objects

The inputs the tool declares

outputslist of objects

The values the tool returns.

enabledboolean

Whether the tool is available to the Agent at all

direct_useboolean or null

Whether the Agent may call this tool on its own, rather than only as a step inside a process.

availability_rulesobject or null

The rule that gates when the tool is offered. null when the tool is always available.

apiobjectOptional

How an api tool calls its HTTP endpoint

codeobjectOptional

The sandboxed Python a code tool runs

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error