Arcanflows — AI Automation Platform for Business

Overview

The Tools API provides a flexible framework for connecting agents to external services, APIs, databases, and custom integrations. Tools can be shared across your tenant or scoped to individual agents with configuration overrides.

Tool Management Endpoints

Method	Endpoint	Description
`GET`	`/v1/tools`	List tools
`POST`	`/v1/tools`	Create tool
`GET`	`/v1/tools/:id`	Get tool
`PUT`	`/v1/tools/:id`	Update tool
`DELETE`	`/v1/tools/:id`	Delete tool
`GET`	`/v1/tools/categories`	List tool categories
`POST`	`/v1/tools/:tool_id/execute`	Execute tool
`GET`	`/v1/tools/:tool_id/executions`	Execution history
`GET`	`/v1/tools/:tool_id/stats`	Tool usage stats

Agent Tool Endpoints

Method	Endpoint	Description
`GET`	`/v1/agents/:agent_id/tools`	List agent's tools
`POST`	`/v1/agents/:agent_id/tools`	Attach tool to agent
`DELETE`	`/v1/agents/:agent_id/tools/:tool_id`	Detach tool from agent
`PATCH`	`/v1/agents/:agent_id/tools/:tool_id`	Update tool config override

Tool Types

Type	Description
`rest_api`	HTTP/REST API endpoints
`function`	Custom server-side functions
`webhook`	Webhook listeners
`database`	Database connections
`script`	External script execution (Python, Node.js)
`custom`	User-defined custom tools

Authentication Types

Type	Description
`none`	No authentication
`api_key`	API key in header or query
`oauth2`	OAuth 2.0 flow
`basic`	Basic authentication (username/password)
`bearer`	Bearer token
`custom`	Custom authentication logic

Slug	Name	Example Services
`crm`	CRM & Sales	Salesforce, HubSpot
`email`	Email & Communication	SendGrid, Gmail
`database`	Databases	PostgreSQL, MongoDB
`analytics`	Analytics & Reporting	Google Analytics, Mixpanel
`automation`	Automation	Zapier, Make
`payment`	Payment & Billing	Stripe, PayPal
`storage`	File Storage	S3, Google Drive
`social`	Social Media	Twitter, LinkedIn
`development`	Development Tools	GitHub, Jira
`webhook`	Webhooks	Custom endpoints
`custom`	Custom Tools	User-defined

List Tools

GET /v1/tools

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max 100)
`category`	string	-	Filter by category slug
`tool_type`	string	-	Filter by tool type
`search`	string	-	Search by name or description
`sort`	string	`-created_at`	Sort field (`-` for descending)

Response

json
{
  "data": [
    {
      "id": "tool_abc123",
      "name": "Salesforce API",
      "slug": "salesforce-api",
      "description": "Query and manage Salesforce CRM data",
      "category": "crm",
      "tool_type": "rest_api",
      "auth_type": "oauth2",
      "is_enabled": true,
      "usage_count": 1520,
      "last_used_at": "2025-12-10T14:30:00Z",
      "created_at": "2025-11-01T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 12,
    "total_pages": 1
  }
}

Example

bash
curl "https://api.arcanflows.io/v1/tools?category=crm&tool_type=rest_api" \
  -H "Authorization: Bearer your_api_key"

Create Tool

POST /v1/tools

Request Body (REST API Example)

json
{
  "name": "Salesforce API",
  "slug": "salesforce-api",
  "description": "Query and manage Salesforce CRM records",
  "category": "crm",
  "tool_type": "rest_api",
  "config": {
    "base_url": "https://yourinstance.salesforce.com/services/data/v57.0",
    "endpoints": {
      "get_account": {
        "method": "GET",
        "path": "/sobjects/Account/{id}"
      },
      "list_contacts": {
        "method": "GET",
        "path": "/query",
        "default_params": {
          "q": "SELECT Id, Name, Email FROM Contact LIMIT 100"
        }
      },
      "create_lead": {
        "method": "POST",
        "path": "/sobjects/Lead"
      }
    },
    "timeout_ms": 10000,
    "retry_count": 2
  },
  "auth_type": "oauth2",
  "auth_config": {
    "token_url": "https://login.salesforce.com/services/oauth2/token",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "api refresh_token"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "endpoint": {
        "type": "string",
        "enum": ["get_account", "list_contacts", "create_lead"],
        "description": "Which endpoint to call"
      },
      "params": {
        "type": "object",
        "description": "Path and query parameters"
      },
      "body": {
        "type": "object",
        "description": "Request body for POST/PUT"
      }
    },
    "required": ["endpoint"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "status_code": { "type": "integer" },
      "data": { "type": "object" }
    }
  }
}

Tool Fields

Field	Type	Required	Description
`name`	string	Yes	Tool display name (max 100 chars)
`slug`	string	No	URL-friendly identifier (auto-generated if omitted)
`description`	string	No	What the tool does
`category`	string	Yes	Category slug
`tool_type`	string	Yes	One of: `rest_api`, `function`, `webhook`, `database`, `script`, `custom`
`config`	object	Yes	Type-specific configuration (see below)
`auth_type`	string	Yes	Authentication method
`auth_config`	object	No	Credentials (encrypted at rest)
`input_schema`	object	No	JSON Schema for input validation
`output_schema`	object	No	JSON Schema for output structure
`is_enabled`	boolean	No	Default `true`

Config by Tool Type

rest_api:

json
{
  "base_url": "https://api.example.com",
  "endpoints": {
    "endpoint_name": {
      "method": "GET|POST|PUT|DELETE",
      "path": "/resource/{id}",
      "default_params": {},
      "default_headers": {}
    }
  },
  "timeout_ms": 5000,
  "retry_count": 3
}

function:

json
{
  "runtime": "python",
  "code": "def execute(params):\n    return {'result': params['input'] * 2}",
  "timeout_ms": 30000,
  "packages": ["requests", "beautifulsoup4"]
}

database:

json
{
  "db_type": "postgresql",
  "host": "db.example.com",
  "port": 5432,
  "database": "mydb",
  "ssl": true,
  "allowed_operations": ["select"],
  "max_rows": 1000
}

webhook:

json
{
  "url": "https://your-app.com/webhook",
  "method": "POST",
  "headers": { "X-Custom-Header": "value" },
  "timeout_ms": 10000
}

script:

json
{
  "runtime": "python",
  "entrypoint": "main.py",
  "timeout_ms": 60000,
  "packages": ["pandas", "openpyxl"]
}

Response

json
{
  "data": {
    "id": "tool_abc123",
    "name": "Salesforce API",
    "slug": "salesforce-api",
    "description": "Query and manage Salesforce CRM records",
    "category": "crm",
    "tool_type": "rest_api",
    "auth_type": "oauth2",
    "is_enabled": true,
    "usage_count": 0,
    "created_at": "2025-12-10T10:00:00Z",
    "updated_at": "2025-12-10T10:00:00Z"
  }
}

Get Tool

GET /v1/tools/:id

Returns the full tool definition including config, schemas, and usage stats.

Response

json
{
  "data": {
    "id": "tool_abc123",
    "name": "Salesforce API",
    "slug": "salesforce-api",
    "description": "Query and manage Salesforce CRM records",
    "category": "crm",
    "tool_type": "rest_api",
    "config": {
      "base_url": "https://yourinstance.salesforce.com/services/data/v57.0",
      "endpoints": {...},
      "timeout_ms": 10000,
      "retry_count": 2
    },
    "auth_type": "oauth2",
    "input_schema": {...},
    "output_schema": {...},
    "is_enabled": true,
    "usage_count": 1520,
    "last_used_at": "2025-12-10T14:30:00Z",
    "created_at": "2025-11-01T09:00:00Z",
    "updated_at": "2025-12-08T11:15:00Z"
  }
}

Note: The auth_config field is never returned in API responses. Credentials are write-only.

Update Tool

PUT /v1/tools/:id

Include only the fields you want to update:

json
{
  "description": "Updated Salesforce integration",
  "config": {
    "timeout_ms": 15000,
    "retry_count": 3
  }
}

Returns the updated tool object.

Delete Tool

DELETE /v1/tools/:id

Response

HTTP/1.1 204 No Content

Warning: Deleting a tool also removes it from all agents. Detach from agents first if you want to preserve agent configurations.

List Tool Categories

GET /v1/tools/categories

Returns all available tool categories.

Response

json
{
  "data": [
    {
      "slug": "crm",
      "name": "CRM & Sales",
      "description": "Customer relationship management tools",
      "icon": "users",
      "tool_count": 3
    },
    {
      "slug": "email",
      "name": "Email & Communication",
      "description": "Email sending and communication tools",
      "icon": "mail",
      "tool_count": 2
    },
    {
      "slug": "database",
      "name": "Databases",
      "description": "Database connection and query tools",
      "icon": "database",
      "tool_count": 1
    }
  ]
}

Execute Tool

POST /v1/tools/:tool_id/execute

Execute a tool directly. The input must conform to the tool's input_schema.

Request Body

json
{
  "input": {
    "endpoint": "get_account",
    "params": {
      "id": "001ABC123"
    }
  }
}

Response

json
{
  "data": {
    "execution_id": "exec_xyz789",
    "status": "completed",
    "output": {
      "status_code": 200,
      "data": {
        "Id": "001ABC123",
        "Name": "Acme Corporation",
        "Industry": "Technology",
        "AnnualRevenue": 5000000
      }
    },
    "execution_time_ms": 342,
    "executed_at": "2025-12-10T14:30:00Z"
  }
}

Execution Errors

json
{
  "data": {
    "execution_id": "exec_xyz790",
    "status": "failed",
    "error": {
      "code": "timeout",
      "message": "Tool execution timed out after 10000ms"
    },
    "execution_time_ms": 10001,
    "executed_at": "2025-12-10T14:31:00Z"
  }
}

Example

bash
curl -X POST "https://api.arcanflows.io/v1/tools/tool_abc123/execute" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "endpoint": "list_contacts",
      "params": {
        "q": "SELECT Id, Name FROM Contact WHERE LastName = '\''Smith'\'' LIMIT 10"
      }
    }
  }'

Execution History

GET /v1/tools/:tool_id/executions

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page
`status`	string	-	Filter: `completed`, `failed`, `timeout`
`after`	string	-	Executions after datetime
`before`	string	-	Executions before datetime

Response

json
{
  "data": [
    {
      "id": "exec_xyz789",
      "tool_id": "tool_abc123",
      "agent_id": "agent_001",
      "status": "completed",
      "input": { "endpoint": "get_account", "params": { "id": "001ABC123" } },
      "output": { "status_code": 200, "data": {...} },
      "execution_time_ms": 342,
      "executed_at": "2025-12-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 85,
    "total_pages": 5
  }
}

Tool Usage Stats

GET /v1/tools/:tool_id/stats

Query Parameters

Parameter	Type	Default	Description
`period`	string	`7d`	Time period: `24h`, `7d`, `30d`, `90d`

Response

json
{
  "data": {
    "tool_id": "tool_abc123",
    "period": "7d",
    "total_executions": 245,
    "successful": 238,
    "failed": 7,
    "success_rate": 97.1,
    "avg_execution_time_ms": 380,
    "p95_execution_time_ms": 820,
    "p99_execution_time_ms": 1450,
    "daily_breakdown": [
      { "date": "2025-12-10", "executions": 42, "failures": 1 },
      { "date": "2025-12-09", "executions": 38, "failures": 2 },
      { "date": "2025-12-08", "executions": 35, "failures": 0 }
    ],
    "top_agents": [
      { "agent_id": "agent_001", "agent_name": "Sales Bot", "executions": 120 },
      { "agent_id": "agent_002", "agent_name": "Support Agent", "executions": 85 }
    ]
  }
}

Agent Tools

List Agent's Tools

GET /v1/agents/:agent_id/tools

Returns all tools attached to a specific agent.

Response

json
{
  "data": [
    {
      "tool_id": "tool_abc123",
      "tool_name": "Salesforce API",
      "tool_type": "rest_api",
      "category": "crm",
      "is_enabled": true,
      "display_order": 1,
      "config_override": null,
      "attached_at": "2025-12-01T10:00:00Z"
    },
    {
      "tool_id": "tool_def456",
      "tool_name": "SendGrid Email",
      "tool_type": "rest_api",
      "category": "email",
      "is_enabled": true,
      "display_order": 2,
      "config_override": {
        "default_from": "[email protected]"
      },
      "attached_at": "2025-12-02T14:00:00Z"
    }
  ]
}

Attach Tool to Agent

POST /v1/agents/:agent_id/tools

json
{
  "tool_id": "tool_abc123",
  "is_enabled": true,
  "display_order": 1,
  "config_override": {
    "default_from": "[email protected]"
  }
}

Parameters

Field	Type	Required	Description
`tool_id`	string	Yes	Tool to attach
`is_enabled`	boolean	No	Default `true`
`display_order`	integer	No	Order in agent's tool list
`config_override`	object	No	Agent-specific config overrides (merged with tool config)

Response

json
{
  "data": {
    "agent_id": "agent_001",
    "tool_id": "tool_abc123",
    "is_enabled": true,
    "display_order": 1,
    "config_override": {
      "default_from": "[email protected]"
    },
    "attached_at": "2025-12-10T10:00:00Z"
  }
}

Detach Tool from Agent

DELETE /v1/agents/:agent_id/tools/:tool_id

Response

HTTP/1.1 204 No Content

Update Tool Config Override

PATCH /v1/agents/:agent_id/tools/:tool_id

Update agent-specific configuration for an attached tool:

json
{
  "is_enabled": true,
  "config_override": {
    "default_from": "[email protected]",
    "timeout_ms": 15000
  }
}

The config_override is merged with the tool's base config at execution time, with override values taking precedence.

Creating Different Tool Types

Function Tool (Python)

json
{
  "name": "QR Code Generator",
  "category": "custom",
  "tool_type": "function",
  "config": {
    "runtime": "python",
    "code": "import qrcode\nimport base64\nfrom io import BytesIO\n\ndef execute(params):\n    img = qrcode.make(params['text'])\n    buffer = BytesIO()\n    img.save(buffer, format='PNG')\n    b64 = base64.b64encode(buffer.getvalue()).decode()\n    return {'image_base64': b64}",
    "timeout_ms": 10000,
    "packages": ["qrcode", "pillow"]
  },
  "auth_type": "none",
  "input_schema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Text or URL to encode" }
    },
    "required": ["text"]
  }
}

Database Tool

json
{
  "name": "Analytics DB",
  "category": "database",
  "tool_type": "database",
  "config": {
    "db_type": "postgresql",
    "host": "analytics-db.internal",
    "port": 5432,
    "database": "analytics",
    "ssl": true,
    "allowed_operations": ["select"],
    "max_rows": 500
  },
  "auth_type": "basic",
  "auth_config": {
    "username": "readonly_user",
    "password": "your_password"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "SQL SELECT query" }
    },
    "required": ["query"]
  }
}

Webhook Tool

json
{
  "name": "Slack Notification",
  "category": "webhook",
  "tool_type": "webhook",
  "config": {
    "url": "https://hooks.slack.com/services/T00/B00/xxxx",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "timeout_ms": 5000
  },
  "auth_type": "none",
  "input_schema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Message text" },
      "channel": { "type": "string", "description": "Channel name" }
    },
    "required": ["text"]
  }
}

Code Examples

Python

python
import requests

API_URL = "https://api.arcanflows.io/v1"
HEADERS = {"Authorization": "Bearer your_api_key"}

# Create a REST API tool
tool = requests.post(f"{API_URL}/tools", headers=HEADERS, json={
    "name": "Weather API",
    "category": "custom",
    "tool_type": "rest_api",
    "config": {
        "base_url": "https://api.openweathermap.org/data/2.5",
        "endpoints": {
            "current": { "method": "GET", "path": "/weather" }
        },
        "timeout_ms": 5000
    },
    "auth_type": "api_key",
    "auth_config": {
        "api_key_header": "appid",
        "api_key_value": "your_owm_key",
        "api_key_location": "query"
    },
    "input_schema": {
        "type": "object",
        "properties": {
            "endpoint": { "type": "string", "enum": ["current"] },
            "params": { "type": "object" }
        },
        "required": ["endpoint"]
    }
}).json()["data"]

# Attach tool to an agent
requests.post(
    f"{API_URL}/agents/agent_001/tools",
    headers=HEADERS,
    json={"tool_id": tool["id"], "is_enabled": True}
)

# Execute the tool
result = requests.post(
    f"{API_URL}/tools/{tool['id']}/execute",
    headers=HEADERS,
    json={
        "input": {
            "endpoint": "current",
            "params": {"q": "London", "units": "metric"}
        }
    }
).json()["data"]

print(f"Status: {result['status']}")
print(f"Time: {result['execution_time_ms']}ms")
print(f"Output: {result['output']}")

JavaScript

javascript
const API_URL = 'https://api.arcanflows.io/v1';
const headers = {
  'Authorization': 'Bearer your_api_key',
  'Content-Type': 'application/json',
};

// Create a webhook tool
const tool = await fetch(`${API_URL}/tools`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Slack Notifier',
    category: 'webhook',
    tool_type: 'webhook',
    config: {
      url: 'https://hooks.slack.com/services/T00/B00/xxxx',
      method: 'POST',
      timeout_ms: 5000,
    },
    auth_type: 'none',
    input_schema: {
      type: 'object',
      properties: {
        text: { type: 'string' },
      },
      required: ['text'],
    },
  }),
}).then(r => r.json());

// Attach to agent
await fetch(`${API_URL}/agents/agent_001/tools`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    tool_id: tool.data.id,
    is_enabled: true,
    display_order: 1,
  }),
});

// Execute
const result = await fetch(`${API_URL}/tools/${tool.data.id}/execute`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    input: { text: 'New lead from Acme Corp!' },
  }),
}).then(r => r.json());

console.log('Execution:', result.data.status, result.data.execution_time_ms + 'ms');

// Check stats
const stats = await fetch(
  `${API_URL}/tools/${tool.data.id}/stats?period=7d`,
  { headers }
).then(r => r.json());

console.log(`Success rate: ${stats.data.success_rate}%`);
console.log(`Avg time: ${stats.data.avg_execution_time_ms}ms`);