API Reference

Authentication

Securely authenticate your CleverSearch API requests.

Auth Methods

Use the secret key for server-side API calls.

Bearer Token

Include your secret API key in the Authorization header.

curl https://api.cleversearch.ai/v1/analysis \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Server Environments

Store keys in environment variables and load them securely.

CLEVERSEARCH_SECRET_KEY=sk_live_...

Key Rotation

Rotate keys regularly and update environments before disabling old keys.

Rotate keys in Settings → API Keys

Server-Side Example

Keep secret keys on the server and read them from environment variables.

// Node.js example
const response = await fetch("https://api.cleversearch.ai/v1/analysis", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLEVERSEARCH_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

Security Notes

Follow these guidelines to keep your credentials safe.

●Never expose secret keys in client-side code

●Use publishable keys only for tracker metadata

●Webhook signatures use a separate secret

●All requests must use HTTPS

Authentication Hardening

Harden auth flows early to avoid security debt during scale.

●Scope keys per service and rotate on schedule.

●Reject client-side secret usage in code review.

●Monitor auth failure patterns by endpoint and environment.

●Alert on repeated invalid signature or token usage.

Execution Phases

Phase 1: Integration

Implement auth, request validation, and core endpoint flow.

Output: Stable API client with retries and typed payloads.

Phase 2: Automation

Add async handling and webhook-driven workflows.

Output: Background jobs connected to reliable event processing.

Phase 3: Hardening

Improve observability, rate-limit handling, and security.

Output: Production-ready monitoring and incident runbooks.

Common Mistakes

●Calling endpoints from client-side code with secret credentials.

●Ignoring 202/async patterns and assuming immediate completion.

●Missing idempotency in webhook consumers, causing duplicate actions.

●Retrying aggressively without backoff during rate limiting.

Success Metrics

Successful Request Rate

>= 99% for non-4xx requests

Indicates resilient client logic and error handling.

Webhook Processing Delay

< 60 seconds median end-to-end

Keeps downstream automation timely and useful.

Auth Error Frequency

< 1% of total calls

Confirms credential management is stable.