Custom AI Tools

Custom tools let Visito call your backend when the AI needs live business data or needs to trigger an approved action. Common examples include looking up an order status, creating a support ticket, checking loyalty points, or updating a customer profile. All endpoints use the M2M base URL:

https://api.visitoai.com/m2m/v1

Tool Model

A tool describes what the AI can call, the JSON input it should provide, and the HTTP endpoint Visito will invoke.

{
  "name": "get_order_status",
  "description": "Look up the latest status for a customer order.",
  "parameters": {
    "type": "object",
    "required": ["order_number"],
    "properties": {
      "order_number": {
        "type": "string",
        "description": "The customer's order number, for example A-1003."
      }
    }
  },
  "endpoint": {
    "url": "https://example.com/visito/tools/get-order-status",
    "method": "POST",
    "timeoutMs": 10000
  },
  "auth": {
    "type": "bearer",
    "value": "tool_backend_secret"
  },
  "active": true,
  "readOnly": true,
  "allowInPlayground": true,
  "propertyIds": []
}

parameters should be a JSON Schema object. Visito uses it to decide when the tool is relevant and to shape the input sent to your endpoint.

Create a Tool

POST /m2m/v1/tools HTTP/1.1
Host: api.visitoai.com
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires the tools:write scope.

{
  "name": "get_order_status",
  "description": "Look up the latest status for a customer order.",
  "parameters": {
    "type": "object",
    "required": ["order_number"],
    "properties": {
      "order_number": {
        "type": "string",
        "description": "The customer's order number."
      }
    }
  },
  "endpoint": {
    "url": "https://example.com/visito/tools/get-order-status",
    "method": "POST"
  },
  "auth": {
    "type": "api_key",
    "headerName": "X-Tool-Key",
    "value": "secret_value"
  },
  "active": true,
  "readOnly": true
}

{
  "tool": {
    "toolId": "tool_...",
    "tenantId": "tenant_...",
    "name": "get_order_status",
    "description": "Look up the latest status for a customer order.",
    "parameters": {},
    "endpoint": {
      "url": "https://example.com/visito/tools/get-order-status",
      "method": "POST"
    },
    "auth": {
      "type": "api_key",
      "headerName": "X-Tool-Key",
      "secretLastFour": "alue",
      "configured": true
    },
    "active": true,
    "readOnly": true,
    "allowInPlayground": true,
    "propertyIds": [],
    "createdAt": "2026-07-12T00:00:00.000Z",
    "updatedAt": "2026-07-12T00:00:00.000Z"
  }
}

Secrets are not returned after creation. Responses only include whether auth is configured and the last four characters when available.

List and Read Tools

GET /m2m/v1/tools HTTP/1.1
Authorization: Bearer visito_m2m_...

Requires tools:read.

{
  "tools": [
    {
      "toolId": "tool_...",
      "name": "get_order_status",
      "active": true,
      "readOnly": true
    }
  ]
}

Read one tool:

GET /m2m/v1/tools/{toolId}

Update or Delete a Tool

Update one or more fields:

PATCH /m2m/v1/tools/{toolId}
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires tools:write.

{
  "active": false,
  "endpoint": {
    "timeoutMs": 15000
  }
}

Delete a tool:

DELETE /m2m/v1/tools/{toolId}
Authorization: Bearer visito_m2m_...

{
  "ok": true,
  "toolId": "tool_...",
  "changed": true
}

Test a Tool

Use the test endpoint before enabling a tool in production conversations.

POST /m2m/v1/tools/{toolId}/test HTTP/1.1
Authorization: Bearer visito_m2m_...
Content-Type: application/json

Requires tools:execute.

{
  "input": {
    "order_number": "A-1003"
  }
}

{
  "ok": true,
  "output": {
    "order_number": "A-1003",
    "status": "delivered",
    "estimated_delivery": "2026-07-10",
    "tracking_url": "https://example.com/orders/A-1003"
  },
  "durationMs": 248
}

Execution Logs

Use logs to audit AI tool calls and diagnose backend failures.

GET /m2m/v1/tools/logs?toolId=tool_...&limit=25
Authorization: Bearer visito_m2m_...

Requires tools:logs:read.

{
  "logs": [
    {
      "logId": "log_...",
      "toolId": "tool_...",
      "toolName": "get_order_status",
      "conversationId": "conv_...",
      "status": "completed",
      "method": "POST",
      "url": "https://example.com/visito/tools/get-order-status",
      "responseStatus": 200,
      "durationMs": 248,
      "startedAt": "2026-07-12T00:00:00.000Z",
      "completedAt": "2026-07-12T00:00:00.248Z"
    }
  ]
}

Read one log:

GET /m2m/v1/tools/logs/{logId}

Endpoint Requirements

Your endpoint must be reachable from Visito’s backend.
Supported methods are GET and POST.
Return JSON whenever possible.
Keep tool responses concise and structured for AI use.
Use readOnly: true for lookup tools that should never mutate state.
Use tool-specific auth secrets instead of broad internal credentials.

Build With Visito

AI Coding Assistants

Tool Model

Create a Tool

List and Read Tools

Update or Delete a Tool

Test a Tool

Execution Logs

Endpoint Requirements

​Tool Model

​Create a Tool

​List and Read Tools

​Update or Delete a Tool

​Test a Tool

​Execution Logs

​Endpoint Requirements

Tool Model

Create a Tool

List and Read Tools

Update or Delete a Tool

Test a Tool

Execution Logs

Endpoint Requirements