API Reference

Analysis Endpoints

Run LLM optimization analyses programmatically and retrieve score details.

Endpoints

Submit URLs or retrieve existing analysis data.

POST /analysis

Submit a URL for scoring and optimization recommendations.

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

POST /analysis/batch

Analyze multiple URLs in a single request.

{"urls": ["https://example.com", "https://example.com/pricing"]}

GET /analysis/{id}

Retrieve analysis results and score breakdowns.

GET https://api.cleversearch.ai/v1/analysis/analysis_123

Response Example

A completed analysis returns scores, entity gaps, and actionable recommendations.

{
  "id": "analysis_123",
  "status": "completed",
  "overall_score": 72,
  "category_scores": {
    "entity_coverage": 68,
    "intent_alignment": 74,
    "structure_quality": 76
  },
  "recommendations": [
    "Expand definition section for primary topic entities",
    "Add FAQ block for comparison intent"
  ]
}

Response Fields

Key properties returned in analysis results.

●overall_score

●category_scores

●recommendations

●entity_gaps

●content_blocks

Analysis Pipeline Design

Design for async processing and robust result retrieval.

●Queue requests in controlled batches to smooth API load.

●Persist analysis IDs and polling state in your system.

●Retry failed jobs with capped exponential backoff.

●Store score snapshots for historical comparisons.

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.