API Documentation

Authentication

Every request requires an API key. Pass it via the X-API-Key header or as a Bearer token.

# Option 1: X-API-Key header
curl https://api.searchclaw.dev/v1/search?q=hello \
  -H "X-API-Key: sc_live_xxxxxxxxxxxxxxxxxx"

# Option 2: Bearer token
curl https://api.searchclaw.dev/v1/search?q=hello \
  -H "Authorization: Bearer sc_live_xxxxxxxxxxxxxxxxxx"

Base URL

https://api.searchclaw.dev/v1

All endpoints are relative to this base URL. HTTPS is required.

Rate Limiting

Rate limits are per API key and depend on your plan tier. Limits are enforced using a sliding window algorithm.

When rate limited, you'll receive a 429 response with a Retry-After header indicating seconds to wait.

Error Handling

All errors return a consistent JSON format:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "status": 429
  }
}

Perform a web search and return structured results from multiple engines.

Parameters

Example Request

curl "https://api.searchclaw.dev/v1/search?q=kubernetes+tutorial&count=5" \
  -H "X-API-Key: sc_live_xxxxxxxxxx"

Example Response

{
  "query": "kubernetes tutorial",
  "results": [
    {
      "title": "Kubernetes Basics - Official Tutorial",
      "url": "https://kubernetes.io/docs/tutorials/kubernetes-basics/",
      "snippet": "Learn Kubernetes basics with this interactive tutorial...",
      "source": "google",
      "position": 1
    }
  ],
  "infobox": {
    "title": "Kubernetes",
    "content": "Kubernetes is an open-source container orchestration system...",
    "url": "https://en.wikipedia.org/wiki/Kubernetes"
  },
  "suggestions": ["kubernetes tutorial for beginners", "kubernetes vs docker"],
  "meta": {
    "total_results": 5,
    "cached": false,
    "response_time_ms": 342,
    "engines_used": ["google", "bing", "duckduckgo"]
  }
}

LLM-optimized search that returns RAG-ready results. Costs 2 credits per query.

Parameters

Same parameters as /v1/search.

Example Request

curl "https://api.searchclaw.dev/v1/search/ai?q=kubernetes+pod+restart+policy" \
  -H "X-API-Key: sc_live_xxxxxxxxxx"

Example Response

{
  "query": "kubernetes pod restart policy",
  "context": "A PodSpec has a restartPolicy field with possible values Always, OnFailure, and Never. The default value is Always. The restart policy applies to all containers in the Pod...",
  "results": [
    {
      "title": "Pod Lifecycle | Kubernetes",
      "url": "https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/",
      "snippet": "A PodSpec has a restartPolicy field with possible values Always, OnFailure, and Never...",
      "source": "google",
      "position": 1
    }
  ],
  "meta": {
    "credits_used": 2,
    "cached": true,
    "response_time_ms": 12
  }
}

Search for news articles. Returns results with publication dates, source names, and thumbnails.

Parameters

Same parameters as /v1/search.

Example Response

{
  "query": "AI startups 2026",
  "results": [
    {
      "title": "Top AI Startups to Watch in 2026",
      "url": "https://example.com/article",
      "snippet": "The AI landscape continues to evolve rapidly...",
      "published_date": "2026-03-01T10:30:00Z",
      "source_name": "TechCrunch",
      "thumbnail": "https://example.com/thumb.jpg",
      "position": 1
    }
  ],
  "meta": {
    "total_results": 10,
    "cached": false,
    "response_time_ms": 456,
    "engines_used": ["google news", "bing news"]
  }
}

Search for images. Returns thumbnails, source URLs, and dimensions.

Parameters

Same parameters as /v1/search.

Example Response

{
  "query": "golden retriever puppy",
  "results": [
    {
      "title": "Golden Retriever Puppy",
      "thumbnail_url": "https://example.com/thumb.jpg",
      "source_url": "https://example.com/page",
      "width": 1200,
      "height": 800,
      "source_name": "Example.com",
      "position": 1
    }
  ],
  "meta": {
    "total_results": 10,
    "cached": false,
    "response_time_ms": 289,
    "engines_used": ["google images", "bing images"]
  }
}

Autocomplete suggestions for a partial query. Fast, cached aggressively.

Parameters

Example Request

curl "https://api.searchclaw.dev/v1/suggest?q=kube" \
  -H "X-API-Key: sc_live_xxxxxxxxxx"

Example Response

[
  "kubernetes",
  "kubernetes tutorial",
  "kubernetes vs docker",
  "kubernetes pods",
  "kubelet"
]

Check your current billing period usage, remaining credits, and plan information.

Example Request

curl "https://api.searchclaw.dev/v1/usage" \
  -H "X-API-Key: sc_live_xxxxxxxxxx"

Example Response

{
  "plan": "pro",
  "billing_period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "credits": {
    "total": 100000,
    "used": 14523,
    "remaining": 85477
  },
  "rate_limit": {
    "requests_per_second": 20
  },
  "usage_today": {
    "queries": 342,
    "cache_hit_rate": 0.64
  }
}

Response Headers

Every API response includes these headers:

SDKs

Official client libraries for quick integration.

Python

pip install searchclaw

from searchclaw import SearchClaw
client = SearchClaw(api_key="sc_live_xxxxxxxxxx")
results = client.search("your query")

Node.js

npm install searchclaw

import { SearchClaw } from 'searchclaw';
const client = new SearchClaw({ apiKey: 'sc_live_xxxxxxxxxx' });
const results = await client.search('your query');