API Reference

CleverSearch API

Build integrations, automate analysis, and power custom optimization workflows.

API Basics

Quick facts to get you started.

●Base URL: https://api.cleversearch.ai/v1

●All requests use HTTPS

●Responses are JSON encoded

●Rate limits are returned in response headers

Quickstart

Send your first request in seconds using your secret API key.

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

Reference Sections

Jump to the API area you need.

Authentication

Use your secret API key in the Authorization header for every request.

Analysis Endpoints

Submit URLs or content payloads to receive LLM optimization scores.

Content Injection

Generate or retrieve inject-ready content blocks for your pages.

Webhooks

Receive events when analyses complete or content updates are ready.

Common Status Codes

Handle these response codes to build reliable integrations.

200 - Success

Request processed successfully and response payload returned.

202 - Accepted

Request queued for async processing. Poll using the returned ID.

400 - Bad Request

Invalid request body, missing required fields, or malformed JSON.

401 - Unauthorized

API key missing, expired, or invalid for this endpoint.

429 - Rate Limited

Too many requests. Use exponential backoff and retry later.

500 - Server Error

Temporary API issue. Retry with backoff and log request IDs.

Integration Readiness

Use these checks before shipping API-backed automation to production.

●Implement retries with exponential backoff for transient errors.

●Store credentials in server environments only.

●Log request/response metadata for observability and debugging.

●Add fallback paths when async jobs are delayed.

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.