Assign Tool to Assistant

This endpoint assigns a tool to one or more assistants, making it available during their conversations. Tools can be assigned to multiple assistants simultaneously.

Path Parameters

tool_id (integer, required): The unique identifier of the tool to assign

Request Body

Request

{
  "assistant_ids": [123, 456, 789],
  "enabled": true
}

Request Fields

assistant_ids (array of integers, required): List of assistant IDs to assign the tool to
enabled (boolean, optional): Whether the tool is enabled for these assistants (default: true)

Response

A successful request returns assignment details:

Response

{
  "success": true,
  "tool_id": 123,
  "assignments": [
    {
      "assistant_id": 123,
      "assistant_name": "Customer Service Bot",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    },
    {
      "assistant_id": 456,
      "assistant_name": "Sales Assistant",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    },
    {
      "assistant_id": 789,
      "assistant_name": "Technical Support",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    }
  ],
  "message": "Tool successfully assigned to 3 assistants"
}

Single Assistant Assignment

You can also assign a tool to a single assistant:

Single Assignment Request

{
  "assistant_ids": [123],
  "enabled": true
}

Single Assignment Response

{
  "success": true,
  "tool_id": 123,
  "assignments": [
    {
      "assistant_id": 123,
      "assistant_name": "Customer Service Bot",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z"
    }
  ],
  "message": "Tool successfully assigned to 1 assistant"
}

Error Responses

404 Not Found - Tool

{
  "detail": "Tool with ID 123 not found"
}

404 Not Found - Assistant

{
  "detail": "Assistant with ID 456 not found in your organization"
}

400 Bad Request - Already Assigned

{
  "detail": "Tool is already assigned to assistant 123"
}

400 Bad Request - Empty Assignment

{
  "detail": "assistant_ids cannot be empty"
}

Unassign Tool

To unassign a tool from assistants, use the unassign endpoint:

Unassign Tool

POST /api/v1/tools/{tool_id}/unassign

Unassign Request

{
  "assistant_ids": [123, 456]
}

List Tool Assignments

Get all current assignments for a tool:

List Assignments

GET /api/v1/tools/{tool_id}/assignments

Assignments Response

{
  "tool_id": 123,
  "tool_name": "get_customer_info",
  "assignments": [
    {
      "assistant_id": 123,
      "assistant_name": "Customer Service Bot",
      "enabled": true,
      "assigned_at": "2024-01-15T16:30:00Z",
      "usage_count": 45,
      "last_used_at": "2024-01-15T18:15:00Z"
    },
    {
      "assistant_id": 456,
      "assistant_name": "Sales Assistant", 
      "enabled": false,
      "assigned_at": "2024-01-15T16:30:00Z",
      "usage_count": 12,
      "last_used_at": "2024-01-15T17:20:00Z"
    }
  ],
  "total_assignments": 2
}

Integration Examples

Node.js Example

const axios = require('axios');

async function assignToolToAssistants(toolId, assistantIds, enabled = true) {
  try {
    const response = await axios.post(`https://api.burki.dev/api/v1/tools/${toolId}/assign`, {
      assistant_ids: assistantIds,
      enabled: enabled
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to assign tool:', error.response.data);
    throw error;
  }
}

async function unassignToolFromAssistants(toolId, assistantIds) {
  try {
    const response = await axios.post(`https://api.burki.dev/api/v1/tools/${toolId}/unassign`, {
      assistant_ids: assistantIds
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to unassign tool:', error.response.data);
    throw error;
  }
}

async function getToolAssignments(toolId) {
  try {
    const response = await axios.get(`https://api.burki.dev/api/v1/tools/${toolId}/assignments`, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Failed to get assignments:', error.response.data);
    throw error;
  }
}

// Usage examples
const result = await assignToolToAssistants(123, [456, 789]);
const assignments = await getToolAssignments(123);
await unassignToolFromAssistants(123, [456]);

Python Example

import requests
from typing import List, Dict, Any

def assign_tool_to_assistants(
    tool_id: int, 
    assistant_ids: List[int], 
    enabled: bool = True
) -> Dict[str, Any]:
    """Assign a tool to multiple assistants."""
    url = f"https://api.burki.dev/api/v1/tools/{tool_id}/assign"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {
        "assistant_ids": assistant_ids,
        "enabled": enabled
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Failed to assign tool: {response.json()['detail']}")

def unassign_tool_from_assistants(
    tool_id: int, 
    assistant_ids: List[int]
) -> Dict[str, Any]:
    """Unassign a tool from multiple assistants."""
    url = f"https://api.burki.dev/api/v1/tools/{tool_id}/unassign"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {"assistant_ids": assistant_ids}
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Failed to unassign tool: {response.json()['detail']}")

def get_tool_assignments(tool_id: int) -> Dict[str, Any]:
    """Get all assignments for a tool."""
    url = f"https://api.burki.dev/api/v1/tools/{tool_id}/assignments"
    headers = {"Authorization": "Bearer YOUR_API_KEY"}
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Failed to get assignments: {response.json()['detail']}")

# Usage examples
result = assign_tool_to_assistants(123, [456, 789])
assignments = get_tool_assignments(123)
unassign_result = unassign_tool_from_assistants(123, [456])

PHP Example

<?php
function assignToolToAssistants($toolId, $assistantIds, $enabled = true) {
    $url = "https://api.burki.dev/api/v1/tools/{$toolId}/assign";
    $headers = [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ];
    
    $data = [
        'assistant_ids' => $assistantIds,
        'enabled' => $enabled
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Failed to assign tool: " . $response);
    }
}

function getToolAssignments($toolId) {
    $url = "https://api.burki.dev/api/v1/tools/{$toolId}/assignments";
    $headers = ['Authorization: Bearer YOUR_API_KEY'];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Failed to get assignments: " . $response);
    }
}

// Usage
$result = assignToolToAssistants(123, [456, 789]);
$assignments = getToolAssignments(123);
?>

Best Practices

Selective Assignment: Only assign tools to assistants that actually need them
Testing: Test tool functionality with specific assistants before broad deployment
Monitoring: Track tool usage per assistant to optimize assignments
Documentation: Document which tools are assigned to which assistants
Performance: Consider the number of tools per assistant for optimal performance

Use Cases

Department-Specific Tools

Scenario: Different tools for different departments

// Assign CRM lookup to sales assistants
await assignToolToAssistants(
  crmToolId, 
  [salesBot1, salesBot2, salesBot3]
);

// Assign technical diagnostics to support assistants  
await assignToolToAssistants(
  diagToolId,
  [supportBot1, supportBot2]
);

Gradual Rollout

Scenario: Rolling out new tools gradually

// Phase 1: Assign to test assistant
await assignToolToAssistants(newToolId, [testAssistant]);

// Phase 2: Assign to pilot group
await assignToolToAssistants(newToolId, [pilot1, pilot2]);

// Phase 3: Full rollout
await assignToolToAssistants(newToolId, allAssistantIds);

Temporary Access

Scenario: Temporary tool access for specific periods

// Assign tool for promotion period
await assignToolToAssistants(promoToolId, marketingBots, true);

// Later: Disable tool after promotion
await assignToolToAssistants(promoToolId, marketingBots, false);

API Documentation

Assistants

Assistant Phone Numbers

Assistant Documents (RAG)

Voice Cloning

Calls

Messaging

Phone Number Management

Call Data

Organization

Webhooks & System

WebSockets

Tools & Custom Actions

Path Parameters

Request Body

Request Fields

Response

Single Assistant Assignment

Error Responses

Unassign Tool

List Tool Assignments

Integration Examples

Best Practices

Use Cases

API Documentation

Assistants

Assistant Phone Numbers

Assistant Documents (RAG)

Voice Cloning

Calls

Messaging

Phone Number Management

Call Data

Organization

Webhooks & System

WebSockets

Tools & Custom Actions

​Path Parameters

​Request Body

​Request Fields

​Response

​Single Assistant Assignment

​Error Responses

​Unassign Tool

​List Tool Assignments

​Integration Examples

​Best Practices

​Use Cases

Path Parameters

Request Body

Request Fields

Response

Single Assistant Assignment

Error Responses

Unassign Tool

List Tool Assignments

Integration Examples

Best Practices

Use Cases