검색 API

PostgreSQL 전문 검색(Supabase FTS)을 사용하여 블로그 내 발행된 포스트를 검색합니다.

포스트 검색

GET /search?q=keyword

파라미터	타입	필수	기본값	설명
`q`	string	예	—	검색어 (최대 100자)
`page`	integer	아니오	1	페이지 번호
`per_page`	integer	아니오	20	페이지당 결과 수 (최대 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
  }
}

검색 동작 방식

PostgreSQL tsvector 전문 검색을 simple 설정으로 사용하며, 영어와 한국어 모두 지원합니다. 여러 단어로 검색하면 AND 로직으로 결합되어 모든 단어가 포함된 결과만 반환됩니다.

검색 결과에는 발행된 포스트만 포함됩니다. 임시저장 및 예약 포스트는 제외됩니다.

에러

상태	원인
400	`q` 파라미터 누락 또는 검색어 100자 초과
400	블로그 미지정 (API 키가 블로그에 바인딩되지 않았거나 `X-Blog-Id` 헤더 누락)

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

참고: 포스트 API | 인증 | Rate Limits