This endpoint retrieves a paginated list of all tools in your organization with advanced filtering, sorting, and search capabilities.

​
Query Parameters

  • page (integer, optional, default: 1): Page number for pagination
  • per_page (integer, optional, default: 12): Number of tools per page (max: 100)
  • tool_type (string, optional): Filter by tool type
    • Allowed values: "endpoint", "python_function", "lambda"
  • is_active (boolean, optional): Filter by active status
  • search (string, optional): Search in tool names, display names, and descriptions
  • sort_by (string, optional, default: "name"): Sort field
    • Allowed values: "name", "display_name", "created_at", "updated_at", "execution_count"
  • sort_order (string, optional, default: "asc"): Sort direction
    • Allowed values: "asc", "desc"

​
Example Requests

curl -X GET "https://api.burki.dev/api/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

A successful request returns a paginated list of tools:
Response
{
  "tools": [
    {
      "id": 123,
      "name": "get_customer_info",
      "display_name": "Customer Information Lookup",
      "description": "Look up customer information by phone number or email",
      "tool_type": "endpoint",
      "configuration": {
        "url": "https://api.yourcompany.com/customers/lookup",
        "method": "GET",
        "timeout_seconds": 30
      },
      "function_definition": {
        "name": "get_customer_info",
        "description": "Look up customer information by phone number or email",
        "parameters": {
          "type": "object",
          "properties": {
            "phone_number": {
              "type": "string",
              "description": "Customer's phone number in E.164 format"
            }
          },
          "required": ["phone_number"]
        }
      },
      "is_active": true,
      "is_public": false,
      "execution_count": 156,
      "success_rate": 94.2,
      "avg_execution_time": 1.24,
      "organization_id": 456,
      "created_by": 789,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T15:45:00Z"
    },
    {
      "id": 124,
      "name": "calculate_loan_payment",
      "display_name": "Loan Payment Calculator",
      "description": "Calculate monthly loan payment based on principal, rate, and term",
      "tool_type": "python_function",
      "configuration": {
        "timeout_seconds": 10
      },
      "function_definition": {
        "name": "calculate_loan_payment",
        "description": "Calculate monthly loan payment and totals",
        "parameters": {
          "type": "object",
          "properties": {
            "principal": {"type": "number"},
            "annual_rate": {"type": "number"},
            "years": {"type": "integer"}
          },
          "required": ["principal", "annual_rate", "years"]
        }
      },
      "is_active": true,
      "is_public": false,
      "execution_count": 89,
      "success_rate": 100.0,
      "avg_execution_time": 0.12,
      "organization_id": 456,
      "created_by": 789,
      "created_at": "2024-01-14T09:15:00Z",
      "updated_at": "2024-01-14T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 12,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

​
Response Fields

Tool Object:
  • id (integer): Unique tool identifier
  • name (string): Tool name (unique within organization)
  • display_name (string): Human-readable name
  • description (string): Tool description
  • tool_type (string): Tool type ("endpoint", "python_function", or "lambda")
  • configuration (object): Tool-specific configuration (sensitive data redacted)
  • function_definition (object): OpenAI function calling schema
  • is_active (boolean): Whether the tool is active
  • is_public (boolean): Whether the tool is publicly visible
  • execution_count (integer): Total number of executions
  • success_rate (float): Success rate percentage (0-100)
  • avg_execution_time (float): Average execution time in seconds
  • organization_id (integer): Organization that owns the tool
  • created_by (integer): User ID who created the tool
  • created_at (string): ISO 8601 creation timestamp
  • updated_at (string): ISO 8601 last update timestamp
Pagination Object:
  • page (integer): Current page number
  • per_page (integer): Items per page
  • total (integer): Total number of tools
  • total_pages (integer): Total number of pages
  • has_next (boolean): Whether there’s a next page
  • has_prev (boolean): Whether there’s a previous page

​
Filtering Examples

​
Error Responses

400 Bad Request 
{
  "detail": "Invalid sort_by field. Must be one of: name, display_name, created_at, updated_at, execution_count"
}
422 Validation Error 
{
  "detail": [
    {
      "loc": ["query", "per_page"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

​
Integration Examples

​
Performance Considerations

  • Pagination: Use appropriate page sizes (default 12, max 100)
  • Filtering: Apply filters to reduce response size
  • Caching: Consider caching results for frequently accessed tool lists
  • Search: Use specific search terms for better performance