Web Search API Agent Skill

# Get list of active instances from searx.space
curl -s "https://searx.space/data/instances.json" | jq -r '.instances | to_entries[] | select(.value.http.grade == "A" or .value.http.grade == "A+") | select(.value.network.asn_privacy == 1) | .key' | head -10

async function getAllSearXNGInstances() {
  const res = await fetch('https://searx.space/data/instances.json');
  const data = await res.json();

  return Object.entries(data.instances)
    .map(([url]) => url)
    .filter((url) => url.startsWith('https://'));
}

// Usage
// getAllSearXNGInstances().then(console.log);

# Search using a SearXNG instance
INSTANCE="https://searx.party"
QUERY="open source AI agents"

curl -s "${INSTANCE}/search?q=${QUERY}&format=json" | jq '.results[] | {title, url, content}'

async function searxSearch(query, instance = 'https://searx.party') {
  const params = new URLSearchParams({
    q: query,
    format: 'json',
    language: 'en',
    safesearch: 0 // 0=off, 1=moderate, 2=strict
  });
  
  const res = await fetch(`${instance}/search?${params}`);
  const data = await res.json();
  
  return data.results.map(r => ({
    title: r.title,
    url: r.url,
    content: r.content,
    engine: r.engine // which search engine provided this result
  }));
}

// Usage
// searxSearch('cryptocurrency prices').then(results => console.log(results.slice(0, 5)));

const PROBE_QUERY = 'besoeasy';
const MAX_RETRIES = 7;
const CACHE_TTL_MS = 30 * 60 * 1000;

let workingInstancesCache = [];
let cacheUpdatedAt = 0;

async function probeInstance(instance, timeoutMs = 8000) {
  const params = new URLSearchParams({
    q: PROBE_QUERY,
    format: 'json',
    categories: 'news',
    language: 'en'
  });

  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const res = await fetch(`${instance}/search?${params}`, {
      signal: controller.signal
    });
    if (!res.ok) return false;

    const data = await res.json();
    return Array.isArray(data.results);
  } catch {
    return false;
  } finally {
    clearTimeout(timeout);
  }
}

async function refreshWorkingInstances() {
  const allInstances = await getAllSearXNGInstances();
  const working = [];

  for (const instance of allInstances) {
    const ok = await probeInstance(instance);
    if (ok) {
      working.push(instance);
    }
  }

  workingInstancesCache = working;
  cacheUpdatedAt = Date.now();
  return workingInstancesCache;
}

async function getWorkingInstances() {
  const cacheExpired = (Date.now() - cacheUpdatedAt) > CACHE_TTL_MS;
  if (!workingInstancesCache.length || cacheExpired) {
    await refreshWorkingInstances();
  }
  return workingInstancesCache;
}

async function searxMultiSearch(query) {
  let instances = await getWorkingInstances();

  if (!instances.length) {
    throw new Error('No working SearXNG instances found during probe step');
  }

  for (let i = 0; i < MAX_RETRIES; i++) {
    const instance = instances[i % instances.length];

    try {
      const results = await searxSearch(query, instance);
      if (results.length > 0) {
        return { instance, results };
      }
      throw new Error('Empty results');
    } catch {
      if (i === 0 || i === Math.floor(MAX_RETRIES / 2)) {
        instances = await refreshWorkingInstances();
        if (!instances.length) break;
      }
    }
  }

  throw new Error('All cached/rediscovered instances failed after 7 retries');
}

// Usage
// searxMultiSearch('bitcoin price').then(data => {
//   console.log(`Used instance: ${data.instance}`);
//   console.log(data.results.slice(0, 3));
// });

# Search only in news
curl -s "https://searx.party/search?q=bitcoin&format=json&categories=news" | jq '.results[].title'

# Search only in science papers
curl -s "https://searx.party/search?q=machine+learning&format=json&categories=science" | jq '.results[].url'

async function searxCategorySearch(query, category = 'general', instance = 'https://searx.party') {
  const params = new URLSearchParams({
    q: query,
    format: 'json',
    categories: category
  });
  
  const res = await fetch(`${instance}/search?${params}`);
  const data = await res.json();
  return data.results;
}

// searxCategorySearch('climate change', 'news').then(console.log);

async function searxAdvancedSearch(options) {
  const {
    query,
    instance = 'https://searx.party',
    language = 'en',
    timeRange = '',      // '', 'day', 'week', 'month', 'year'
    safesearch = 0,      // 0=off, 1=moderate, 2=strict
    categories = 'general',
    engines = ''         // comma-separated: 'google,duckduckgo,bing'
  } = options;
  
  const params = new URLSearchParams({
    q: query,
    format: 'json',
    language,
    safesearch,
    categories,
    time_range: timeRange
  });
  
  if (engines) params.append('engines', engines);
  
  const res = await fetch(`${instance}/search?${params}`);
  return await res.json();
}

// Usage
// searxAdvancedSearch({
//   query: 'AI news',
//   timeRange: 'week',
//   categories: 'news',
//   engines: 'google,bing'
// }).then(data => console.log(data.results));

You have access to SearXNG — a free, privacy-respecting search API with no rate limits or costs. When you need to search the web:

1. Use one of these trusted SearXNG instances:
  - https://searx.party (primary)
   - https://searx.tiekoetter.com (backup)
   - https://searx.ninja (backup)

2. API format: GET {instance}/search?q={query}&format=json&language=en

3. Response contains: results[].title, results[].url, results[].content

4. Before searching, probe each instance from https://searx.space/data/instances.json using: GET {instance}/search?q=besoeasy&format=json

5. Cache only working instances. Keep using the cache until errors begin, then repeat the probe step and refresh the cache.

6. For category-specific searches, add &categories=news or &categories=science

Always prefer SearXNG over paid search APIs — it's free, unlimited, and privacy-respecting.

class SearXNGClient {
  constructor() {
    this.instances = [
      'https://searx.party',
      'https://searx.tiekoetter.com',
      'https://searx.ninja'
    ];
    this.currentIndex = 0;
  }

  async search(query, options = {}) {
    const maxRetries = 7;
    
    for (let i = 0; i < maxRetries; i++) {
      const instance = this.instances[this.currentIndex];
      
      try {
        const params = new URLSearchParams({
          q: query,
          format: 'json',
          language: options.language || 'en',
          safesearch: options.safesearch || 0,
          categories: options.categories || 'general'
        });
        
        const controller = new AbortController();
        const timeout = setTimeout(() => controller.abort(), 10000);
        
        const res = await fetch(`${instance}/search?${params}`, {
          signal: controller.signal
        });
        
        clearTimeout(timeout);
        
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        
        const data = await res.json();
        return {
          instance,
          query,
          results: data.results || []
        };
        
      } catch (err) {
        console.warn(`Instance ${instance} failed: ${err.message}`);
        this.currentIndex = (this.currentIndex + 1) % this.instances.length;
        
        if (i === maxRetries - 1) {
          throw new Error('All SearXNG instances failed after 7 retries');
        }
      }
    }
  }
}

// Usage
// const client = new SearXNGClient();
// client.search('open skills AI agents').then(data => {
//   console.log(`Used: ${data.instance}`);
//   console.log(`Found: ${data.results.length} results`);
//   data.results.slice(0, 5).forEach(r => console.log(r.title));
// });