Search Posts

GET/api/v1/content/posts/search

Overview

Performs full-text search across published blog posts, ranking results by relevance. Searches across title, excerpt, and body content.

Authentication

info

No authentication required - Client is resolved from the X-Content-Domain header, which the Cloudflare Worker sets automatically based on the request domain.

Headers

Header	Type	Required	Description
X-Content-Domain	string	Yes	The domain used to resolve the client tenant. Automatically set by the CF Worker; set manually for external frontend integrations.

Query Parameters

Parameter	Type	Default	Description
q	string	required	Search query (minimum 2 characters)
page	integer	1	Page number for pagination
page_size	integer	20	Number of results per page

Response

Same shape as the List Posts endpoint. Results are ranked by relevance to the search query.

postsarray

Array of matching post objects, ranked by relevance

totalinteger

Total number of matching posts

pageinteger

Current page number

page_sizeinteger

Number of results per page

Example Request

cURL

curl -s "https://spideriq.ai/api/v1/content/posts/search?q=google+maps&page=1&page_size=10" \
  -H "X-Content-Domain: your-domain.com"

Python

import requests

resp = requests.get(
    "https://spideriq.ai/api/v1/content/posts/search",
    params={"q": "google maps", "page": 1, "page_size": 10},
    headers={"X-Content-Domain": "your-domain.com"}
)
data = resp.json()

print(f"Found {data['total']} results")
for post in data["posts"]:
    print(f"  - {post['title']}")

JavaScript

const q = encodeURIComponent("google maps");
const resp = await fetch(
  `https://spideriq.ai/api/v1/content/posts/search?q=${q}&page=1&page_size=10`,
  { headers: { "X-Content-Domain": "your-domain.com" } }
);
const data = await resp.json();

console.log(`Found ${data.total} results`);
data.posts.forEach(post => console.log(`  - ${post.title}`));

Example Response

{
  "posts": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "slug": "how-to-scrape-google-maps",
      "title": "How to Scrape Google Maps at Scale",
      "excerpt": "A step-by-step guide to extracting business data from Google Maps.",
      "cover_image_url": "https://cdn.spideriq.ai/blog/maps-guide-cover.webp",
      "status": "published",
      "published_at": "2026-03-15T09:00:00Z",
      "author_name": "Martin Shein",
      "author_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "author": {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "full_name": "Martin Shein",
        "slug": "martin-shein",
        "avatar_url": "https://cdn.spideriq.ai/authors/martin.webp"
      },
      "reading_time": 8,
      "view_count": 1243,
      "is_featured": true,
      "tags": ["google-maps", "scraping", "seo"]
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10
}

Status Codes

Status Code	Meaning	Description
200	OK	Search results returned successfully
422	Unprocessable Entity	Missing or invalid q parameter (minimum 2 characters)

Related Endpoints

📋

List Posts

List all published posts

📃

Get Post

Get a single post by slug

⭐

Featured Posts

List featured posts

tags

List Tags

List all tags with post counts