Skip to Content
API referenceTools API

Tools API

This page is for developers who want to list, create and run tools from their own code. A tool is one thing an assistant can do in one of your systems, such as “look up an order” or “issue a refund”. For example, a test script can run the “track shipment” tool against a known order to check your order system still answers. In the app, tools live under Tools; see Tools.

Tools in the UI

REST API reference for managing tools.

Endpoints

MethodEndpointDescription
GET/organizations/{orgId}/toolsList tools
POST/organizations/{orgId}/toolsCreate a tool
GET/tools/:idGet tool by ID
PATCH/tools/:idUpdate a tool
DELETE/tools/:idDelete a tool
POST/organizations/{orgId}/tools/:id/executeExecute a tool

List tools

curl https://api.almyty.com/organizations/{orgId}/tools \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "success": true,
  "data": {
    "tools": [
      {
        "id": "tool-uuid",
        "name": "get_users",
        "description": "Retrieve a list of users",
        "type": "api",
        "status": "active",
        "parameters": {
          "type": "object",
          "properties": {
            "page": { "type": "integer" }
          }
        }
      }
    ]
  }
}

Create a tool

curl -X POST https://api.almyty.com/organizations/{orgId}/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "calculate_total",
    "description": "Calculate order total with tax",
    "type": "function",
    "executionMethod": "custom",
    "parameters": {
      "type": "object",
      "properties": {
        "price": { "type": "number" },
        "quantity": { "type": "integer" },
        "taxRate": { "type": "number", "default": 0.1 }
      },
      "required": ["price", "quantity"]
    },
    "code": "return { total: parameters.price * parameters.quantity * (1 + parameters.taxRate) };"
  }'

Execution methods

executionMethod says how the tool runs, and each method keeps its definition in its own field.

executionMethodRequired fieldsPage
httphttpConfig.method, httpConfig.pathHTTP tools
customcodeJavaScript tools
graphqlgraphqlConfig.endpoint, graphqlConfig.queryGraphQL tools
soapsoapConfig.endpoint, soapConfig.operationSOAP tools
grpcgrpcConfig.endpoint, grpcConfig.serviceName, grpcConfig.methodName, grpcConfig.protoDefinitiongRPC tools
llmllmConfig.providerId, llmConfig.promptTemplateLLM tools
sdksdkConfigSDK tools

For graphql, soap and grpc, a create without the matching config, or with code, is refused with a 400. The endpoint (and for grpc the proto) may be left out when the tool is linked to a connected API with apiId.

Execute a tool

curl -X POST https://api.almyty.com/organizations/{orgId}/tools/{id}/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "price": 29.99,
      "quantity": 3
    }
  }'

Response

{
  "success": true,
  "data": {
    "result": { "total": 98.97 },
    "duration": 12,
    "status": "success"
  }
}
APIsGateways API