SDK Documentation

Unbrowse integrates as an installable skill.

Install it once.

Then other agents can call the Unbrowse tools.

Install

Install Unbrowse from GitHub:

npx skills add https://github.com/getfoundry/unbrowse

This registers the Unbrowse skill with your skills runtime.

Environment Variables

Configure the runtime with these environment variables:

# Required
UNBROWSE_API_KEY=your_api_key_here

# Optional
UNBROWSE_BASE_URL=https://api.unbrowse.ai  # Custom API endpoint
UNBROWSE_TIMEOUT=30000                      # Request timeout (ms)
UNBROWSE_MAX_RETRIES=3                      # Auto-retry failed requests

Available Tools

The Unbrowse skill exposes these tools to AI assistants:

unbrowse_search

Search for skills (abilities) by natural language query.

Input Schema:

{
  query: string;      // Natural language description
  limit?: number;     // Max results (default: 10)
  category?: string;  // Filter by category
}

Output:

{
  abilities: [
    {
      id: string;
      name: string;
      description: string;
      category: string;
      parameters: {
        [key: string]: {
          type: string;
          description: string;
          required: boolean;
        }
      };
    }
  ]
}

Example:

{
  "query": "search flights",
  "category": "travel",
  "limit": 5
}

unbrowse_execute

Execute a specific ability with parameters.

Input Schema:

{
  ability_id: string;
  params: Record<string, any>;
  timeout?: number;  // Optional execution timeout
}

Output:

{
  success: boolean;
  data: any;           // Structured result from ability
  execution_time: number;  // Milliseconds
  trace_id?: string;   // Present when execution tracing is enabled
  safety?: {
    label: "safe" | "needs_confirmation";
    mutated?: boolean;
  };
}

Example:

{
  "ability_id": "united_search_flights_v2",
  "params": {
    "origin": "NYC",
    "destination": "LAX",
    "departure_date": "2025-01-15",
    "passengers": 1
  }
}

unbrowse_list_categories

List all available ability categories.

Input: None

Output:

{
  categories: [
    {
      name: string;
      slug: string;
      ability_count: number;
      description: string;
    }
  ]
}

Advanced Usage

Chaining Multiple Abilities

AI assistants can automatically chain Unbrowse abilities:

User: "Research Snowflake's competitors and post a summary to Slack"

AI Assistant:
1. unbrowse_search("competitor research") → finds SpyFu ability
2. unbrowse_execute("spyfu_competitor_search", {domain: "snowflake.com"})
3. [Process results, generate summary]
4. unbrowse_search("post to Slack") → finds Slack ability
5. unbrowse_execute("slack_post_message", {channel: "#research", text: "..."})

Error Handling

Unbrowse returns structured error information:

{
  success: false,
  error: {
    code: "RATE_LIMIT_EXCEEDED",
    message: "Daily execution limit reached (100/100)",
    suggestions: [
      "Upgrade to Pro tier for 1,000 executions/day",
      "Try again tomorrow",
      "Contact support for temporary limit increase"
    ],
    retry_after: 43200  // Seconds until retry allowed
  }
}

Caching

The runtime can cache search results for a short window to reduce latency.

Cache behavior:

• Search queries are cached by query string

• Ability definitions cached by ID

• Cache invalidated on any execution error

• Can be disabled with UNBROWSE_DISABLE_CACHE=true

Monitoring Usage

Track your Unbrowse usage in the dashboard:

agent.unbrowse.ai/dashboard

Metrics available:

• Total searches performed

• Total abilities executed

• Success/failure rates

• Most-used abilities

Billing is disabled in the current beta.

Security

API Key Protection

Never commit API keys to version control.

Best practices:

• Use environment variables

• Store in OS-specific secure storage (Keychain, etc.)

• Rotate keys regularly

• Use separate keys for dev/prod

Request Signing

All requests are signed with your API key. The server validates:

• API key authenticity

• Request timestamp (prevents replay attacks)

• Request integrity (prevents tampering)

Debugging

Enable debug logging:

UNBROWSE_DEBUG=true

Enable this in the environment where your skills runtime runs.

This logs:

• All search queries

• Ability executions

• API responses

• Error details

• Performance metrics

Debug output:

You should see extra logs in your runtime output.

Performance

Typical latencies:

• Ability search: 20-50ms (cached: <5ms)

• Ability execution: 200-500ms

• Total workflow: <1 second

Optimization tips:

• Use specific queries ("LinkedIn post with image" vs "social media")

• Reuse ability IDs instead of searching repeatedly

• Execute abilities in parallel when possible

Troubleshooting

"Unbrowse skill not found"

Solution:

npx skills add https://github.com/getfoundry/unbrowse

"Invalid API key"

Solution:

• Verify API key at agent.unbrowse.ai/settings

• Check environment variable is set correctly

• Ensure no extra spaces or quotes in config

"Rate limit exceeded"

Solution:

• Check usage at agent.unbrowse.ai/dashboard

• Upgrade to Pro tier

• Wait for daily limit reset (midnight UTC)

"Ability execution failed"

Solutions:

• Check ability parameters match requirements

• Verify you have necessary credentials/subscriptions

• Try a different ability variant

• Report persistent failures to support

Next Steps

• Integration Examples - Detailed use cases

• API Reference - REST API docs (for custom integrations)

• Authentication - Auth methods and security

---

Questions? Join our Discord.