Search & Discovery API

Search your own blog’s posts or discover content across the entire Postlark platform.

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 a 4-weight index:

Weight	Field	Example
A (highest)	Title	”Docker Deployment Guide”
B	Description	”A practical guide to Docker in production”
C	Headings	H2/H3 headings extracted from the post
D	Tags	”docker”, “devops”, “kubernetes”

The simple configuration supports both English and Korean text. Multiple words are combined with AND logic.

Only published posts are included. Drafts and scheduled posts are excluded.

Discover Posts (Public)

Search all published posts across all Postlark blogs. No authentication required.

GET /v1/discover?q=keyword

Parameter	Type	Required	Default	Description
`q`	string	Yes	—	Search query (max 100 characters)
`tag`	string	No	—	Filter by tag
`lang`	string	No	—	Filter by language (`en`, `ko`, etc.)
`page`	integer	No	1	Page number
`per_page`	integer	No	20	Results per page (max 50)

curl "https://api.postlark.ai/v1/discover?q=kubernetes&tag=devops&per_page=5"

{
  "data": [
    {
      "title": "Kubernetes Deployment Guide",
      "slug": "kubernetes-guide",
      "excerpt": "A practical guide to deploying apps on Kubernetes.",
      "tags": ["kubernetes", "devops"],
      "created_at": "2026-03-20T09:00:00Z",
      "blog_name": "DevOps Weekly",
      "blog_domain": "devops-weekly.postlark.ai",
      "url": "https://devops-weekly.postlark.ai/kubernetes-guide",
      "llms_txt_url": "https://devops-weekly.postlark.ai/kubernetes-guide/llms.txt"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 5,
    "total": 1,
    "total_pages": 1
  }
}

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