Search API

Search published posts within your blog using PostgreSQL full-text search (via Supabase FTS).

Search Posts

GET /search?q=keyword

Parameter	Type	Required	Default	Description
`q`	string	Yes	—	Search query (max 100 characters)
`page`	integer	No	1	Page number
`per_page`	integer	No	20	Results per page (max 50)

curl "https://api.postlark.ai/v1/search?q=getting+started&page=1&per_page=10" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

{
  "data": [
    {
      "slug": "getting-started-with-postlark",
      "title": "Getting Started with Postlark",
      "meta_description": "A quick guide to publishing your first post with Postlark.",
      "tags": ["tutorial", "quickstart"],
      "created_at": "2026-03-15T09:00:00Z"
    },
    {
      "slug": "advanced-getting-started",
      "title": "Advanced Setup Guide",
      "meta_description": "Take your Postlark blog to the next level.",
      "tags": ["tutorial", "advanced"],
      "created_at": "2026-03-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "total_pages": 1
  }
}

How Search Works

Search uses PostgreSQL tsvector full-text search with the simple configuration, which supports both English and Korean text. Multiple words in the query are combined with AND logic — all terms must match.

Only published posts are included in search results. Drafts and scheduled posts are excluded.

Errors

Status	Cause
400	Missing `q` parameter or query exceeds 100 characters
400	Blog not resolved (API key not bound to a blog, or missing `X-Blog-Id` header)

{
  "error": "bad_request",
  "message": "q parameter is required"
}

See also: Posts API | Authentication | Rate Limits