콘텐츠로 이동
Postlark Docs

검색 & 디스커버리 API

내 블로그의 포스트를 검색하거나 Postlark 플랫폼 전체의 콘텐츠를 디스커버리할 수 있습니다.

포스트 검색

섹션 제목: “포스트 검색”
GET /search?q=keyword
파라미터타입필수기본값설명
qstring예—검색어 (최대 100자)
pageinteger아니오1페이지 번호
per_pageinteger아니오20페이지당 결과 수 (최대 50)
curl
curl "https://api.postlark.ai/v1/search?q=getting+started&page=1&per_page=10" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"
Response (200)
{
  "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 전문 검색을 4단계 가중치 인덱스로 사용합니다:

가중치필드예시
A (최고)제목”Docker 배포 가이드”
B설명”Docker를 활용한 프로덕션 배포 방법”
C헤딩포스트에서 추출한 H2/H3 제목
D태그”docker”, “devops”, “kubernetes”

simple 설정으로 영어와 한국어 모두 지원합니다. 여러 단어는 AND 로직으로 결합됩니다.

검색 결과에는 발행된 포스트만 포함됩니다.

포스트 디스커버리 (공개)

섹션 제목: “포스트 디스커버리 (공개)”

전체 Postlark 블로그의 발행된 포스트를 검색합니다. 인증이 필요 없습니다.

GET /v1/discover?q=keyword
파라미터타입필수기본값설명
qstring예—검색어 (최대 100자)
tagstring아니오—태그 필터
langstring아니오—언어 필터 (en, ko 등)
pageinteger아니오1페이지 번호
per_pageinteger아니오20페이지당 결과 수 (최대 50)
curl (인증 불필요)
curl "https://api.postlark.ai/v1/discover?q=kubernetes&tag=devops&per_page=5"
Response (200)
{
  "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
  }
}

에러

섹션 제목: “에러”
상태원인
400q 파라미터 누락 또는 검색어 100자 초과
400블로그 미지정 (API 키가 블로그에 바인딩되지 않았거나 X-Blog-Id 헤더 누락)
에러 응답
{
  "error": "bad_request",
  "message": "q parameter is required"
}

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