Skip to main content
The Search API provides AI-powered search functionality that can detect URLs in queries and automatically trigger SEO audits.

​
Search and Auto-Audit

This endpoint requires authentication. Include a valid JWT bearer token in the Authorization header.

​
POST /api/v1/search

Process a search query and optionally trigger an audit if a URL is detected.
​
query
string
required
The search query. If a URL is detected, an audit will be automatically started.

​
Response

​
response
string
AI-generated response to the query
​
suggestions
array
List of suggested actions or follow-up queries
​
audit_id
integer
ID of the automatically created audit (if a URL was detected)
​
audit_started
boolean
Whether an audit was automatically triggered

​
Example Request

curl -X POST https://api.example.com/api/v1/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze https://example.com for SEO issues"
  }'

​
Example Response

{
  "response": "I've detected a URL in your query and started an SEO audit for https://example.com",
  "suggestions": [
    "View audit progress",
    "Configure audit settings",
    "Check previous audits for this domain"
  ],
  "audit_id": 123,
  "audit_started": true
}

​
Auto-Audit Behavior

When a URL is detected in the search query:
  1. URL Extraction: The system uses regex to extract valid HTTP/HTTPS URLs
  2. Audit Creation: Automatically creates an audit with default settings:
    • max_crawl: 30 pages
    • max_audit: 3 pages (detailed analysis)
  3. Background Processing: The audit runs asynchronously via Celery worker
  4. User Association: The audit is linked to the authenticated user
Monitor audit progress using the SSE endpoint or polling the audit status endpoint.

​
Error Codes

CodeDescription
401Missing or invalid authentication token
422Invalid request format
500Internal server error
503Celery worker unavailable (falls back to sync mode in debug)

​
Next Steps

Audit API

View and manage created audits

SSE API

Monitor audit progress in real-time

Build docs developers (and LLMs) love

Get started for freeTalk to us