Skip to main content

​
Initialize the ToolSet

Start by creating a StackOneToolSet instance: 
from stackone_ai import StackOneToolSet

# Initialize the toolset
toolset = StackOneToolSet()
account_id = 'your-customer-account-id'

​
Get Tools

Use glob patterns to retrieve specific tools: 
# Get all HRIS tools
hris_tools = toolset.get_tools('hris_*', account_id=account_id)

# Get all ATS tools
ats_tools = toolset.get_tools('ats_*', account_id=account_id)

# Get specific list operations
list_tools = toolset.get_tools('hris_list_*', account_id=account_id)

​
Execute Tools

​
Basic Tool Execution

# Get a specific tool
employee_tool = tools.get_tool('hris_list_employees')

# Execute with parameters using call() method
employees = employee_tool.call(limit=10, include_details=True)

print(employees)

​
Alternative Execution Methods

# Method 1: call() with keyword arguments (recommended)
result = employee_tool.call(id="employee-123", include_details=True)

# Method 2: execute() with dictionary
result = employee_tool.execute({"id": "employee-123", "include_details": True})

​
Error Handling

from stackone_ai.exceptions import StackOneError, ToolExecutionError

try:
    result = employee_tool.call(id="employee-123")
    print("Success:", result)
except ToolExecutionError as e:
    print(f"Tool execution failed: {e.message}")
except StackOneError as e:
    print(f"StackOne API error: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
Tool Filtering

​
Advanced Filtering Patterns

# Get all tools for multiple categories
all_tools = toolset.get_tools(['hris_*', 'ats_*'], account_id=account_id)

# Exclude dangerous operations
safe_tools = toolset.get_tools(['hris_*', '!hris_delete_*'], account_id=account_id)

# Get only read operations
read_only_tools = toolset.get_tools(['*_list_*', '*_get_*'], account_id=account_id)

​
List Available Tools

# Get all available tools
tools = toolset.get_tools('*', account_id=account_id)

# List tool names
tool_names = tools.list_tools()
print('Available tools:', tool_names)

# Get specific tool information
tool_info = tools.get_tool_info('hris_list_employees')
print('Tool info:', tool_info)

​
Working with Results

​
Processing Tool Results

employees = employee_tool.call(limit=50)

# Process the results
for employee in employees.data:
    print(f"{employee.first_name} {employee.last_name} - {employee.email}")

# Check pagination
if employees.next:
    print('More results available')

​
Handling Different Data Types

# List operations return arrays
departments = dept_tool.call()
print(f"Found {len(departments.data)} departments")

# Get operations return single objects
employee = employee_tool.call(id='emp_123')
print(f"Employee: {employee.data.display_name}")

​
Environment Configuration

​
Using Environment Variables

import os
from stackone_ai import StackOneToolSet

# Set in your .env file
# STACKONE_API_KEY=your_api_key
# STACKONE_ACCOUNT_ID=your_account_id

toolset = StackOneToolSet(
    api_key=os.getenv('STACKONE_API_KEY')
)

# Use environment account ID as default
account_id = os.getenv('STACKONE_ACCOUNT_ID') or 'fallback-account-id'

​
Using python-dotenv

from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

from stackone_ai import StackOneToolSet

toolset = StackOneToolSet(
    api_key=os.getenv('STACKONE_API_KEY')
)

​
Dynamic Account Handling

# Handle multiple customer accounts
customer_accounts = ['account-1', 'account-2', 'account-3']

for account_id in customer_accounts:
    tools = toolset.get_tools('hris_list_employees', account_id=account_id)
    employees = tools.get_tool('hris_list_employees').call()

    print(f"Account {account_id}: {len(employees.data)} employees")

​
Next Steps