Search API
Run a real-time web search and optionally scrape the top results in the same request. The API returns ranked, citation-ready JSON for agents and applications.
https://search.venym.io/api/v1/searchExecute a real-time web search with optional automatic scraping.
https://search.venym.io/api. API-key routes use standard Authorization: Bearer <your-api-key> authentication; Clerk browser sessions are not required.First Search
curl -X POST https://search.venym.io/api/v1/search \
-H "Authorization: Bearer $VENYM_SEARCH_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"query": "latest AI developments",
"max_results": 5
}'Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Required | The query to search. Whitespace is trimmed; length is limited to 1,000 characters. Example: |
max_results | integer | Optional | Maximum number of ranked results to return. Allowed range: 1–50. Default: 10 Example: |
auto_scrape_top | integer | Optional | Scrape the first N result URLs and include them in scraped_content. Allowed range: 0–10. Default: 0 Example: |
include_contacts | boolean | Optional | Extract contacts from scraped content. Requires Starter or higher. Default: false Example: |
include_social | boolean | Optional | Extract social profiles from scraped content. Requires Builder or higher. Default: false Example: |
Predictable Charges
Search reserves the maximum requested auto-scrape charge, then refunds pages that do not complete.
Response Format
| Field | Type | Description |
|---|---|---|
query | string | The normalized query that was executed. |
search_results | array | Ranked results with title, link, snippet, position, and optional date. |
scraped_content | array | Results from automatic scraping; failed pages include an error field. |
contacts | array | Present when include_contacts is true. |
social_profiles | array | Present when include_social is true. |
credits_used | integer | Credits charged after completed work is settled. |
remaining_credits | integer | Account balance after settlement. |
results_count | integer | Number of search_results returned. |
scraped_count | integer | Number of scraped pages without an error. |
{
"query": "latest AI developments",
"search_results": [
{
"title": "Example result",
"link": "https://example.com/article",
"snippet": "A result snippet returned by the search engine.",
"position": 1,
"date": null
}
],
"scraped_content": [],
"credits_used": 2,
"remaining_credits": 4998,
"results_count": 1,
"scraped_count": 0
}Response Codes
code, request_id, timestamp, and documentation_url.