Tools (Beta)

The Tools API provides direct access to individual research capabilities, giving you granular control over your data gathering workflows. These endpoints are currently in beta and available by invitation only.

Overview

While our Agents API provides complete AI-driven workflows, the Tools API gives you direct access to the underlying research tools. This is perfect when you need:

• Granular control over specific data gathering tasks
• Lower latency for simple lookups
• Predictable outputs with structured data support
• Cost optimization by using only what you need

Authentication

All tool endpoints require authentication via API key:

curl -X POST https://api.utopianlabs.ai/v1/tools/research-website \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "question": "What does this company do?"
  }'

Endpoint Patterns

Tools can be called using two patterns:

Pattern 1: Tool-specific endpoints

POST /v1/tools/{tool-name}

Pattern 2: Generic endpoint with tool parameter

POST /v1/tools

With the tool specified in the request body:

{
  "tool": "research-website",
  "url": "https://example.com",
  "question": "What does this company do?"
}

Structured Output Support

All tools support structured outputs via the output_schema parameter. This allows you to define the exact shape of the data you want to receive:

{
  "url": "https://example.com",
  "question": "What products does this company offer?",
  "output_schema": {
    "products": [{
      "name": "string",
      "description": "string",
      "pricing": "string"
    }]
    }
  }
}

The tool will extract and structure the information according to your schema, making it easy to integrate into your existing data pipelines.

Rate Limiting

All tool endpoints are rate-limited to ensure fair usage:

• Default limit: 10 requests per minute
• Much higher limits are available on request

Available Tools

Common Response Format

All tools return a consistent response format:

{
  "output": "string or structured object based on your schema"
}

Best Practices

1. Use structured outputs when you need specific data formats
2. Cache responses when appropriate to reduce API calls
3. Handle rate limits gracefully with exponential backoff
4. Validate inputs before making API calls
5. Monitor usage to optimize costs

Getting Started

Ready to start using the Tools API?