SDK · REST API

REST API

The canonical HTTP contract for Venym Search. No SDK dependency is required.

Base URL

Use https://search.venym.io/api.

01 · Authentication

Bearer API Keys

Authorization headercURL

# Every paid request uses this header
Authorization: Bearer VENYM_SEARCH_API_KEY

API routes are explicitly separate from Clerk browser authentication. Send the Venym API key exactly as Authorization: Bearer <your-api-key>.

02 · Endpoints

Public Contract

POSThttps://search.venym.io/api/v1/search

Real-time web search with optional automatic scraping. Base charge: 2 credits.

POSThttps://search.venym.io/api/v1/scrape

Scrape one URL and return structured primary_content. Base charge: 5 credits.

GEThttps://search.venym.io/api/v1/validate

Validate a key and return status, plan, and credits without consuming credits.

GEThttps://search.venym.io/api/health

Public application health. No API key required.

03 · Requests

Search and Scrape

POST /api/v1/searchcURL

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}'

POST /api/v1/scrapecURL

curl -X POST https://search.venym.io/api/v1/scrape \
  -H "Authorization: Bearer $VENYM_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com","extract_options":["title","text"]}'

GET /api/v1/validatecURL

curl https://search.venym.io/api/v1/validate \
  -H "Authorization: Bearer $VENYM_SEARCH_API_KEY"

04 · Responses

Success Shape

Search responseJSON

{
  "query": "latest AI developments",
  "search_results": [],
  "scraped_content": [],
  "credits_used": 2,
  "remaining_credits": 4998,
  "results_count": 0,
  "scraped_count": 0
}

Search and Scrape return credits_used and remaining_credits. Scrape returns its page data under primary_content.

05 · Errors

Stable Error Shape

401 responseJSON

{
  "error": "Invalid or missing API key",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "request_id": "req_abc123",
  "timestamp": "2026-08-29T12:00:00.000Z",
  "documentation_url": "https://search.venym.io/docs/errors"
}

400Invalid request body or parameter.

401Missing or invalid API key.

402Insufficient credits.

403Plan-gated feature unavailable.

429Endpoint rate limit exceeded.

500Unexpected server error; retain request_id.

06 · Rate Headers

Rate-Limit Metadata

X-RateLimit-Limit

Maximum requests in the current endpoint window.

X-RateLimit-Remaining

Requests remaining in the current window.

X-RateLimit-Reset

Unix timestamp when the window resets.

Retry-After

Seconds to wait on a 429 response.

Current endpoint windows are 60 requests/minute for Search and 10 requests/minute for Scrape, tracked per client IP on the active service instance.

Preserve X-Request-ID and the JSON request_id whenever you report a failed request. Never log the API key.