Search & Discovery

Powerful search and discovery capabilities to help users and AI agents find the right tools and services. Semantic search, personalized recommendations, and intelligent suggestions.

Semantic Search

Natural language queries across tools and memories

Recommendations

Personalized suggestions based on usage patterns

Popular Tools

Discover trending and widely-used tools

Categories & Tags

Browse tools by category and tags

Advanced Filters

Filter by category, rating, response time

Search History

Track and learn from past searches

Universal Search

Search Everything

Search across tools and memories simultaneously with a single query.

GET/search

Query Parameters

Parameter	Type	Description
`q`required	`string`	Search query
`limit`	`integer`	Number of results (default: 10, max: 50)
`type`	`string`	Filter by type: tools, memories, or all

Request

GET /search?q=weather%20forecast&limit=10

Response

{
  "results": {
    "tools": [
      {
        "type": "tool",
        "id": "weather_forecast",
        "name": "Weather Forecast API",
        "description": "Get 7-day weather forecasts for any location",
        "service_id": "550e8400-e29b-41d4-a716-446655440000",
        "relevance_score": 0.95,
        "popularity_score": 0.87
      }
    ],
    "memories": [
      {
        "type": "memory",
        "id": "mem_123456789",
        "summary": "User frequently checks weather forecasts for travel planning",
        "relevance_score": 0.82,
        "created_at": "2024-12-15T10:00:00Z"
      }
    ]
  },
  "query": "weather forecast",
  "total_results": 15
}

Tool Search

Search for Tools

GET/search/tools

Query Parameters

Parameter	Type	Description
`q`required	`string`	Search query
`category`	`string`	Filter by category (ai, data, communication, etc.)
`subscription_type`	`string`	Filter by subscription tier: free, basic, premium
`tags`	`string`	Comma-separated tags
`sort`	`string`	Sort order: relevance, popular, newest, rating
`limit`	`integer`	Number of results

Response

{
  "tools": [
    {
      "id": "translate_text",
      "name": "Universal Translator",
      "description": "Translate text between 100+ languages",
      "service": {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "Translation Service",
        "category": "ai"
      },
      "parameters": {
        "text": "string",
        "target_language": "string",
        "source_language": "string (optional)"
      },
      "subscription_type": "free",
      "stats": {
        "total_uses": 15420,
        "success_rate": 0.998,
        "average_response_time": 125
      },
      "relevance_score": 0.94
    }
  ],
  "query": "translate",
  "total_results": 5
}

Discovery Features

Popular Tools

Discover trending and popular tools based on usage.

GET/search/popular

Query Parameters

Parameter	Type	Description
`limit`	`integer`	Number of results (default: 10)
`timeframe`	`string`	Time period: day, week, month, all
`category`	`string`	Filter by category

Response

{
  "popular_tools": [
    {
      "rank": 1,
      "tool_id": "weather_current",
      "name": "Current Weather",
      "service_name": "Weather API",
      "usage_count": 5420,
      "unique_users": 342,
      "growth_rate": 0.15,
      "category": "data",
      "description": "Get real-time weather data"
    }
  ],
  "timeframe": "week",
  "generated_at": "2024-12-19T10:00:00Z"
}

Personalized Recommendations

Get tool recommendations based on your usage patterns and preferences.

GET/search/recommendations

Response

{
  "recommendations": [
    {
      "tool_id": "weather_forecast",
      "name": "Weather Forecast",
      "reason": "Based on your frequent use of weather_current",
      "confidence_score": 0.89,
      "service": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Weather API"
      },
      "complementary_tools": ["weather_alerts", "climate_data"]
    }
  ],
  "based_on": {
    "usage_patterns": true,
    "similar_users": true,
    "tool_relationships": true
  }
}

Search Suggestions

Get autocomplete suggestions as users type.

GET/search/suggestions

Request

GET /search/suggestions?partial=wea&limit=5

Response

{
  "suggestions": [
    {
      "text": "weather",
      "type": "keyword",
      "popularity": 0.95
    },
    {
      "text": "weather forecast",
      "type": "phrase",
      "popularity": 0.87
    },
    {
      "text": "Weather API",
      "type": "service",
      "service_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "partial": "wea"
}

Categories & Tags

Browse by Category

GET/search/categories

Response

{
  "categories": [
    {
      "id": "ai",
      "name": "AI & Machine Learning",
      "description": "AI-powered services",
      "tool_count": 125,
      "popular_tags": ["nlp", "vision", "ml"]
    },
    {
      "id": "data",
      "name": "Data & Information",
      "description": "Data services and APIs",
      "tool_count": 89,
      "popular_tags": ["weather", "finance"]
    }
  ]
}

Browse by Tags

GET/search/tags

Response

{
  "tags": [
    {
      "name": "nlp",
      "display_name": "Natural Language",
      "tool_count": 45,
      "trending": true
    },
    {
      "name": "translation",
      "display_name": "Translation",
      "tool_count": 23,
      "trending": false
    }
  ],
  "category": "ai"
}

Search Operators

Use these operators to build complex search queries.

Operator	Description	Example
`AND`	Both terms must match	`weather AND forecast`
`OR`	Either term matches	`weather OR climate`
`NOT`	Exclude term	`weather NOT radar`
`"..."`	Exact phrase	`"weather forecast"`
`*`	Wildcard	`trans*`
`:`	Field search	`category:ai`

ℹ️Complex Query Example

(weather OR climate) AND forecast NOT radar category:data

Filter Options

Filter	Description	Values
`category`	Service category	ai, data, communication, etc.
`subscription_type`	Subscription tier	free, basic, premium
`min_rating`	Minimum rating	0.0 - 5.0
`tags`	Service tags	Comma-separated
`has_free_tier`	Has free tier	true, false
`response_time`	Max response time	milliseconds

SDK Example

TypeScript - Smart Tool Discovery

import { Aphelion } from 'aphelion';

const client = new Aphelion({ apiKey: process.env.APHELION_API_KEY });

class ToolDiscovery {
  async searchTools(query: string, filters: object = {}) {
    return client.search.tools({
      q: query,
      limit: 10,
      ...filters
    });
  }

  async getRecommendations() {
    const { recommendations } = await client.search.recommendations({ limit: 5 });
    return recommendations;
  }

  async discoverByCategory(category: string) {
    // Get popular tools in category
    const popular = await client.search.popular({
      category,
      limit: 5,
      timeframe: 'week'
    });

    // Get all tools in category
    const allTools = await this.searchTools('*', {
      category,
      sort: 'rating'
    });

    return { popular, all: allTools };
  }

  async getSuggestions(partial: string) {
    return client.search.suggestions({ partial, limit: 5 });
  }
}

// Usage
const discovery = new ToolDiscovery();

// Search for translation tools
const translators = await discovery.searchTools('translate', {
  category: 'ai'
});

// Get personalized recommendations
const recommendations = await discovery.getRecommendations();
console.log('Recommended for you:', recommendations);

// Explore AI category
const aiTools = await discovery.discoverByCategory('ai');
console.log('Popular AI tools:', aiTools.popular);

// Autocomplete
const suggestions = await discovery.getSuggestions('wea');
console.log('Suggestions:', suggestions);

Search Analytics

Search History

GET/search/history

Response

{
  "searches": [
    {
      "query": "weather forecast",
      "timestamp": "2024-12-19T10:00:00Z",
      "result_count": 5,
      "clicked_results": [
        "weather_forecast",
        "climate_data"
      ]
    }
  ]
}

Search Insights

GET/search/insights

Response

{
  "insights": {
    "most_searched_categories": [
      "data",
      "ai"
    ],
    "frequent_queries": [
      "weather",
      "translate",
      "calculate"
    ],
    "discovery_rate": 0.34,
    "search_success_rate": 0.89
  }
}