Search API

The Search API allows Oliver to search the internet using Bing Search to provide up-to-date information in conversations.

Note: Search functionality requires appropriate permissions and is subject to rate limiting.

Search Query

Perform a web search query using Bing Search API.

POST /api/v1/search

Execute a search query and return relevant web results.

Headers

Authorization: Bearer <your_api_token>
Content-Type: application/json

Request Body

{
  "query": "latest financial regulations 2025",
  "chat_id": 123,
  "message_id": 456,
  "count": 10,
  "offset": 0,
  "market": "en-US",
  "safe_search": "moderate"
}

Parameters

Parameter	Type	Required	Description
query	string	Yes	The search query string (max 1000 characters)
chat_id	integer	No	Chat ID to associate search with
message_id	integer	No	Message ID that triggered the search
count	integer	No	Number of results to return (default: 10, max: 50)
offset	integer	No	Offset for pagination (default: 0)
market	string	No	Market/locale for search results (default: en-US)
safe_search	string	No	Safe search level: off, moderate, strict (default: moderate)

Response

{
  "success": true,
  "data": {
    "query": "latest financial regulations 2025",
    "search_id": "search_abc123def456",
    "total_results": 1250000,
    "results": [
      {
        "id": "result_1",
        "title": "New Financial Regulations for 2025",
        "url": "https://example.com/financial-regulations-2025",
        "description": "Comprehensive overview of the latest financial regulations taking effect in 2025, including new SEC and FINRA requirements...",
        "display_url": "example.com/financial-regulations-2025",
        "published_date": "2025-01-15T08:30:00Z",
        "snippet": "The Securities and Exchange Commission has announced new regulatory frameworks..."
      },
      {
        "id": "result_2",
        "title": "SEC Announces Updated Compliance Requirements",
        "url": "https://sec.gov/news/press-release/2025-01",
        "description": "The Securities and Exchange Commission today announced updated compliance requirements for investment advisors...",
        "display_url": "sec.gov/news/press-release/2025-01",
        "published_date": "2025-01-10T14:20:00Z",
        "snippet": "Investment advisors must comply with new record-keeping requirements..."
      }
    ],
    "related_searches": [
      "SEC regulations 2025",
      "FINRA compliance updates",
      "Investment advisor requirements"
    ]
  },
  "message": "Search completed successfully"
}

Search History

Retrieve search history for a user or chat.

GET /api/v1/search/history

Get paginated search history with optional filtering.

Headers

Authorization: Bearer <your_api_token>

Query Parameters

Parameter	Type	Required	Description
chat_id	integer	No	Filter by specific chat ID
date_from	string	No	Start date filter (ISO 8601 format)
date_to	string	No	End date filter (ISO 8601 format)
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)

Response

{
  "success": true,
  "data": [
    {
      "id": "search_abc123def456",
      "query": "latest financial regulations 2025",
      "chat_id": 123,
      "message_id": 456,
      "result_count": 10,
      "total_results": 1250000,
      "created_at": "2025-03-18T10:30:00Z"
    },
    {
      "id": "search_def456ghi789",
      "query": "SEC compliance requirements",
      "chat_id": 123,
      "message_id": 458,
      "result_count": 15,
      "total_results": 890000,
      "created_at": "2025-03-18T09:15:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1,
    "has_next_page": false,
    "has_previous_page": false
  }
}

Search Result Details

Get detailed information about a specific search result.

GET /api/v1/search/{search_id}

Retrieve detailed information about a previous search query.

Headers

Authorization: Bearer <your_api_token>

Path Parameters

Parameter	Type	Required	Description
search_id	string	Yes	Unique identifier for the search

Response

{
  "success": true,
  "data": {
    "id": "search_abc123def456",
    "query": "latest financial regulations 2025",
    "chat_id": 123,
    "message_id": 456,
    "total_results": 1250000,
    "search_parameters": {
      "count": 10,
      "offset": 0,
      "market": "en-US",
      "safe_search": "moderate"
    },
    "results": [
      {
        "id": "result_1",
        "title": "New Financial Regulations for 2025",
        "url": "https://example.com/financial-regulations-2025",
        "description": "Comprehensive overview of the latest financial regulations...",
        "display_url": "example.com/financial-regulations-2025",
        "published_date": "2025-01-15T08:30:00Z",
        "snippet": "The Securities and Exchange Commission has announced...",
        "metadata": {
          "domain": "example.com",
          "language": "en",
          "region": "US"
        }
      }
    ],
    "related_searches": [
      "SEC regulations 2025",
      "FINRA compliance updates"
    ],
    "created_at": "2025-03-18T10:30:00Z"
  }
}

Error Handling

The Search API returns specific error codes for different failure scenarios:

Error Code	HTTP Status	Description
search_query_too_long	422	Search query exceeds maximum length of 1000 characters
search_quota_exceeded	429	Daily or monthly search quota has been exceeded
search_service_unavailable	503	Bing Search service is temporarily unavailable
invalid_search_parameters	422	One or more search parameters are invalid

Example Error Response

{
  "success": false,
  "error": {
    "code": "search_quota_exceeded",
    "message": "Daily search quota has been exceeded. Quota resets at midnight UTC.",
    "details": {
      "quota_limit": 1000,
      "quota_used": 1000,
      "quota_reset_at": "2025-03-19T00:00:00Z"
    }
  }
}

Rate Limits

Search API endpoints have the following rate limits:

Search Query: 20 requests per minute
Search History: 60 requests per minute
Search Details: 60 requests per minute

Best Practices

Cache Results: Cache search results locally to avoid redundant API calls
Meaningful Queries: Use specific, relevant search terms for better results
Handle Pagination: Use offset parameter for large result sets
Monitor Quotas: Track your search quota usage to avoid service interruptions
Error Handling: Implement proper error handling for quota limits and service availability

Important: Search results are cached for 24 hours to improve performance and reduce API costs. Identical queries within this window will return cached results.