REST API

REST API Documentation

Complete REST API reference for Venym Search services. Use HTTP requests directly without any SDK dependencies for maximum flexibility and control.

Base URL

All API requests should be made to https://www.search.venym.io/api/v1

Authentication

All requests require authentication using your API key in the Authorization header.

Required Authentication Header

cURL

# Authentication Header
Authorization: Bearer sk_live_YOUR_API_KEY_API_KEY_api_key_here

# Alternative format (if your client doesn't support Bearer)
Authorization: sk_live_YOUR_API_KEY_API_KEY_api_key_here

Important Notes:

• Your API key starts with sk_live_YOUR_API_KEY_API_KEY for production
• Keep your API key secure and never expose it in client-side code
• Use environment variables to store your API key
• API keys are tied to your account and billing plan

Core Endpoints

Endpoint	Method	Description	Credits
/v1/search	POST	Real-time web search with automatic result extraction	1-2 per request
/v1/scrape	POST	Extract content from any webpage, bypass protections	2-5 per request
/v1/usage	GET	Get current API usage statistics and credits	Free
/v1/validate	GET	Validate API key and check account status	Free

Search API

POST

https://www.search.venym.io/api/v1/search

Real-time web search with automatic result extraction

Search the web in real-time and get structured results with automatic content extraction.

Search Request Example

Scrape API

POST

https://www.search.venym.io/api/v1/scrape

Extract content from any webpage, bypass protections

Extract content from any webpage with advanced parsing and protection bypassing.

Scrape Request Example

Response Format

All successful API responses follow a consistent JSON format:

Successful Response Example

JSON

{
  "search_results": [
    {
      "title": "AI Breakthrough: New Language Model Achieves Human-Level Reasoning",
      "link": "https://example.com/ai-news",
      "snippet": "Researchers announce significant advancement in AI reasoning capabilities...",
      "position": 1,
      "date": "2025-01-15",
      "relevance_score": 0.95
    }
  ],
  "credits_used": 1,
  "remaining_credits": 4999,
  "results_count": 10,
  "processing_time_ms": 1250,
  "request_id": "req_abc123"
}

Standard Fields

credits_used - Credits consumed by request

remaining_credits - Credits left in account

processing_time_ms - Request processing time

request_id - Unique request identifier

Content Type

All responses use application/json

UTF-8 encoding for all text content

Timestamps in ISO 8601 format

Numeric IDs as strings for consistency

Error Responses

Error responses include detailed information to help debug issues:

Error Response Example

JSON

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED", 
  "details": "You have exceeded the rate limit for your plan. Please wait before making more requests.",
  "retry_after": 60,
  "request_id": "req_def456",
  "timestamp": "2025-01-15T10:30:00Z",
  "documentation_url": "https://docs.search.venym.io/errors"
}

HTTP Status Codes

200

Request successful

Example: Normal API response with data

400

Bad Request

Invalid request parameters

Example: Missing required field or invalid JSON

401

Unauthorized

Invalid or missing API key

Example: API key not found or malformed

402

Payment Required

Insufficient credits

Example: Account has no remaining credits

429

Too Many Requests

Rate limit exceeded

Example: Too many requests per minute for plan

500

Internal Server Error

Server error occurred

Example: Temporary service issue

Rate Limiting

All requests include rate limit headers for tracking usage:

Rate Limit Headers

x-ratelimit-limit - Requests allowed per window

x-ratelimit-remaining - Requests remaining

x-ratelimit-reset - Window reset time (Unix)

x-ratelimit-window - Window duration (seconds)

Handling Limits

Check remaining requests before making calls

Implement exponential backoff for retries

Respect retry-after header on 429 responses

Best Practices

Request Optimization

• Always set appropriate timeouts (30-60 seconds)

• Use compression headers (Accept-Encoding: gzip)

• Include User-Agent header for identification

• Validate request data before sending

• Handle all possible HTTP status codes

Security

• Store API keys in environment variables

• Use HTTPS for all requests

• Validate SSL certificates

• Never log API keys or sensitive data

• Rotate API keys regularly

REST API

REST API Documentation

Complete REST API reference for Venym Search services. Use HTTP requests directly without any SDK dependencies for maximum flexibility and control.

Base URL

All API requests should be made to https://www.search.venym.io/api/v1

Authentication

All requests require authentication using your API key in the Authorization header.

Required Authentication Header

cURL

# Authentication Header
Authorization: Bearer sk_live_YOUR_API_KEY_API_KEY_api_key_here

# Alternative format (if your client doesn't support Bearer)
Authorization: sk_live_YOUR_API_KEY_API_KEY_api_key_here

Important Notes:

• Your API key starts with sk_live_YOUR_API_KEY_API_KEY for production
• Keep your API key secure and never expose it in client-side code
• Use environment variables to store your API key
• API keys are tied to your account and billing plan

Core Endpoints

Endpoint	Method	Description	Credits
/v1/search	POST	Real-time web search with automatic result extraction	1-2 per request
/v1/scrape	POST	Extract content from any webpage, bypass protections	2-5 per request
/v1/usage	GET	Get current API usage statistics and credits	Free
/v1/validate	GET	Validate API key and check account status	Free

Search API

POST

https://www.search.venym.io/api/v1/search

Real-time web search with automatic result extraction

Search the web in real-time and get structured results with automatic content extraction.

Search Request Example

Scrape API

POST

https://www.search.venym.io/api/v1/scrape

Extract content from any webpage, bypass protections

Extract content from any webpage with advanced parsing and protection bypassing.

Scrape Request Example

Response Format

All successful API responses follow a consistent JSON format:

Successful Response Example

JSON

{
  "search_results": [
    {
      "title": "AI Breakthrough: New Language Model Achieves Human-Level Reasoning",
      "link": "https://example.com/ai-news",
      "snippet": "Researchers announce significant advancement in AI reasoning capabilities...",
      "position": 1,
      "date": "2025-01-15",
      "relevance_score": 0.95
    }
  ],
  "credits_used": 1,
  "remaining_credits": 4999,
  "results_count": 10,
  "processing_time_ms": 1250,
  "request_id": "req_abc123"
}

Standard Fields

credits_used - Credits consumed by request

remaining_credits - Credits left in account

processing_time_ms - Request processing time

request_id - Unique request identifier

Content Type

All responses use application/json

UTF-8 encoding for all text content

Timestamps in ISO 8601 format

Numeric IDs as strings for consistency

Error Responses

Error responses include detailed information to help debug issues:

Error Response Example

JSON

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED", 
  "details": "You have exceeded the rate limit for your plan. Please wait before making more requests.",
  "retry_after": 60,
  "request_id": "req_def456",
  "timestamp": "2025-01-15T10:30:00Z",
  "documentation_url": "https://docs.search.venym.io/errors"
}

HTTP Status Codes

200

Request successful

Example: Normal API response with data

400

Bad Request

Invalid request parameters

Example: Missing required field or invalid JSON

401

Unauthorized

Invalid or missing API key

Example: API key not found or malformed

402

Payment Required

Insufficient credits

Example: Account has no remaining credits

429

Too Many Requests

Rate limit exceeded

Example: Too many requests per minute for plan

500

Internal Server Error

Server error occurred

Example: Temporary service issue

Rate Limiting

All requests include rate limit headers for tracking usage:

Rate Limit Headers

x-ratelimit-limit - Requests allowed per window

x-ratelimit-remaining - Requests remaining

x-ratelimit-reset - Window reset time (Unix)

x-ratelimit-window - Window duration (seconds)

Handling Limits

Check remaining requests before making calls

Implement exponential backoff for retries

Respect retry-after header on 429 responses

Best Practices

Request Optimization

• Always set appropriate timeouts (30-60 seconds)

• Use compression headers (Accept-Encoding: gzip)

• Include User-Agent header for identification

• Validate request data before sending

• Handle all possible HTTP status codes

Security

• Store API keys in environment variables

• Use HTTPS for all requests

• Validate SSL certificates

• Never log API keys or sensitive data

• Rotate API keys regularly