발행

GET /v1/posts

최근에 올린 글 목록이에요. 최신순으로 오고, 답글은 이 목록에 섞이지 않아요.

페이지 넘기기

POST /v1/posts

연결된 계정 하나 이상에 글을 올려요.

curl -X POST https://api.posendy.com/v1/posts \
  -H "authorization: Bearer $POSENDY_KEY" \
  -H "content-type: application/json" \
  -d '{
    "content": "Now with images",
    "accountIds": ["acc_01H..."],
    "mediaIds": ["med_01H..."]
  }'

GET /v1/posts/{id}

발행 하나와 대상별 상태를 줘요.

대상 상태

발행 하나에 채널마다 줄이 하나씩 있어요. publishing은 올리는 중, published는 채널의 글 id와 주소를, failed는 실패 이유를 담고 있어요.

{id}에 넣을 수 있는 값

글을 가리키는 값이면 돼요. 발행 id(post_…), 채널이 준 글 id, shortcode, 글 링크 중 하나를 넣어요. 링크는 encodeURIComponent로 감싸서 경로 한 칸으로 보내요. POST /v1/engagement/like와 /v1/replies/{replyId} 호출의 postId도 같은 값을 받아요.

• 채널 앱에서 직접 쓴 글은 처음 한 번 채널에서 찾아 기록으로 가져와요. 그래서 댓글, 지표, 수정, 삭제를 할 수 있어요. 같은 링크로 다시 부르면 채널을 부르지 않고 포샌디 기록을 읽어요.
• shortcode로 찾을 때는 그 계정의 최근 글(최대 500편)을 읽어요. 더 오래된 글은 scanned와 함께 post_not_in_recent로 답해요. 그때는 채널이 준 글 id를 넣어요.
• 이 워크스페이스가 연결하지 않은 채널의 글은 post_not_owned예요.
• 다른 사람 블로그의 네이버 글은 naver_wrong_blog예요. 댓글과 공감은 ownerHandle과 externalId로 POST /v1/engagement/reply, POST /v1/engagement/like에 보내요.
• 포샌디의 YouTube 하루 한도가 다 찬 날에는 YouTube 링크가 429 youtube_quota_exhausted로 와요.

예약과 초안

scheduledAt을 넣으면 글을 scheduled로 보관했다가 그 시각에 포샌디가 모든 채널로 보내요. draft: true를 넣으면 누군가 publish를 부르거나 대시보드에서 보내기 전까지 아무것도 나가지 않아요.

• 두 경우 모두 status가 scheduled나 draft로 와요.
• PATCH로 고치고, /publish로 앞당겨 보내고, DELETE로 지워요.
• scheduledAt은 시간대 오프셋이 꼭 있어야 하고, 10분 뒤부터 1년 안까지예요.
• 채널 자체 예약 기능도 있어요(options.youtube.publishAt, options.facebook.scheduledPublishTime, options.naver_blog.scheduledAt). API로는 그대로 쓸 수 있지만 대시보드에는 보이지 않아요. 한 글에 예약 시각이 두 개면 서로 어긋날 수 있으니 하나만 써요.

채널마다 다른 본문

모든 채널이 options.<채널>.content를 받아요. 이 값이 있으면 그 채널에는 공통 본문 대신 이 본문이 나가고, 글자 수와 미디어 검사도 이 본문으로 해요. 이 값을 쓰면 Threads용 500자 글과 네이버 블로그용 마크다운 본문을 호출 한 번에 같이 보낼 수 있어요. 채널이 그 밖에 받는 값은 GET /v1/platforms의 options에 있어요.

PATCH /v1/posts/{id}

예약 글이나 초안을 보내기 전에 고쳐요.

• 보내지 않은 값은 그대로 남아요. 네이버에만 가는 글에서 mediaIds를 빼면 새 본문의 media: 참조가 사진 목록이 돼요.
• options는 통째로 바뀌어요.
• threadItems는 체인 전체를 바꾸고, content만 보내면 첫 항목만 바뀌어요.
• 이미 올라간 글의 수정은 비동기예요. wait: true면 결과가 나올 때까지(최대 75초) 응답을 기다리고, 넘으면 202와 함께 글을 다시 읽으라는 next를 줘요.
• 네이버 임시저장이 중간에 끊기면 네이버 임시저장함에서 찾아보고, 있으면 가져와요.
• publish_naver_draft로 올린 글은 네이버 에디터에서 쓴 글과 같은 방식으로 고쳐요. 첫 수정 요청이 지금 원문을 409 naver_source_required로 돌려주고, sourceVersion과 함께 다시 보내면 같은 주소에 다시 써요. 네이버에 있던 사진과 서식은 그대로 남아요.
• 포샌디로 올린 네이버 글도 올린 사진 파일이 정리된 뒤(올리고 하루쯤 지나면)에는 같은 방식이에요. 옵션만 고치면 바로 반영되고, 본문을 고치면 지금 원문이 먼저 와요.

POST /v1/posts/{id}/publish

예약 글이나 초안을 지금 보내요. 예약 발송과 같은 함수를 써서 두 번 나가지 않아요.

POST /v1/posts/{id}/retry

실패한 대상만 다시 보내요. 이미 올라간 대상은 건너뛰어요.

• 네이버 임시저장 직후 끊긴 대상(naver_draft_unknown)이나 제때 확인되지 않은 네이버 답글(naver_reply_unknown)은 본문에 {"force": true}를 넣어야 다시 보내요.
• 같은 계정에 같은 내용과 파일의 다른 글이 이미 있으면 그 글 id와 함께 409 duplicate_post로 답하고 아무것도 보내지 않아요. {"force": true}면 그래도 보내요.

DELETE /v1/posts/{id}

채널에서 글을 지우고 포샌디 기록에 삭제로 표시해요.

예약 글이나 초안은 채널에 아직 아무것도 없어서 포샌디 기록만 지워요. 이미 올라간 글은 채널에서 먼저 지우고, 포샌디 기록은 지운 것으로 표시해서 남겨 둬요.

채널에 이미 있는 글 읽기

포샌디 기록에는 포샌디로 올린 글만 있어요. 아래 엔드포인트는 채널 자체를 읽거나 올릴 채널을 골라요. list_channel_posts, get_quota, open_post, select_channels 도구가 쓰는 라우트라서 REST로 불러도 같은 답이 와요.

GET /v1/posts/{id}/thread

글 하나와 댓글, 지표를 한 번에 가져와요.

GET /v1/channels/posts

지금 채널에 있는 글이에요. 채널 앱에서 직접 쓴 글도 나와요.

쿼리

GET /v1/channels/quota

24시간 한도를 얼마나 썼는지 채널이 알려 주는 값이에요.

GET /v1/channels/bridge

네이버 블로그 브리지(브라우저 확장)가 켜져 있는지, 꺼져 있으면 어떻게 켜는지 알려 줘요.

GET /v1/channels/publish-options

발행 전에 채널에 물어봐야 하는 값이에요. TikTok(준비 중) 전용이에요. 글이 나갈 닉네임, 이 계정이 지금 고를 수 있는 공개 범위, 올릴 수 있는 상태인지, 영상 길이 상한을 줘요. 다른 채널은 not_supported예요.

GET /v1/channels/instagram/audio

Instagram 계정 하나가 릴스에 넣을 수 있는 음악과 원본 소리예요. options.instagram.audio에 넣어요. Instagram 전용이고 Facebook으로 연결한 계정만 돼요. query가 없으면 그 계정의 인기 목록이 오고, query가 있으면 Meta의 로열티 프리 음악(Sound Collection)에서만 찾아요. 그래서 가수나 곡 이름으로 찾아도 그 곡은 안 나와요.

POST /v1/accounts/select

연결된 채널 중 어디에 올릴지 골라요.

POST /v1/accounts/:id/refresh

채널 정보(네이버 블로그 카테고리, Pinterest 보드 등)를 다시 읽어요. 브라우저 확장을 최대 1분 기다려요.

PUT /v1/accounts/:id/pinterest/default-board

Pinterest(준비 중)에서 글에 options.pinterest.boardId가 비어 있을 때 핀을 올릴 기본 보드를 정해요. 연결의 보드 목록에 있는 보드만 받아요. 연결한 뒤에 만든 보드라면 refresh를 먼저 불러요.

GET /v1/naver/blog/diagnose

네이버 블로그의 공개 RSS(최근 글, 최대 50편)를 읽고 제목이 검색을 노리고 쓰였는지 재요.

• 검색 의도어(가격, 방법, 후기)가 든 제목 비율, 날짜나 회차로 시작하는 제목 수, 한 달 글 수, 카테고리, 제목에 반복되는 말을 돌려줘요. 반복되는 말은 조사해 볼 후보이고, 실제로 검색되는 키워드라는 뜻은 아니에요.
• 읽은 날짜 범위를 같이 줘요. 글이 드문 블로그의 50편을 블로그 전체로 착각하지 않게 하려는 거예요.
• 사용자와 상관없이 24시간 캐시돼요. 캐시에 없을 때만 사람당 하루 20회 한도를 써요. 네이버 API 키는 필요 없어요.

POST /v1/naver/keywords/judge

네이버 검색 키워드를 측정하고, 글 하나에 쓸 키워드 세트를 골라요. 키워드를 펼치지는 않으니 가진 키워드를 보내요. 월간 검색수(검색광고), 블로그 문서수, 월 발행량(API HUB), 키워드별 판정, 같은 의도의 메인 1개 + 서브 2~5개 세트를 돌려줘요. 결과는 사용자와 상관없이 7일 캐시되고, 사용자당 하루 60회, 600개 키워드까지 돼요.

POST /v1/naver/keywords/measure

판정과 세트 없이 측정만 해요. withDocs: false면 문서수는 건너뛰어요.

POST /v1/naver/keywords/expand

AI나 API 키 사용자를 위해 네이버 자동완성으로 씨앗 키워드를 한 단계 펼쳐요(대시보드에서는 브라우저가 해요). 그 사람의 포샌디 크롬 확장이 켜져 있으면 확장이 그 사람 인터넷 연결로 창 없이 가져오고, 아니면 서버가 가져와요. 찾은 단어, 어느 씨앗에서 나왔는지, 어느 경로로 받았는지(via)를 줘요. 둘 다 안 되면 503 naver_autocomplete_unavailable이에요. 그때는 키워드 목록을 judge에 바로 넘겨요.

돌려주는 값은 이래요.

GET /v1/naver/keywords/reports

저장한 키워드 조사 기록(judge에 save: true)을 최신순으로 줘요. 언제 무엇을 넣었는지, 첫 세트의 메인과 서브, 세트마다 붙여넣을 프롬프트까지 와요. 기록은 사람 단위라서, 워크스페이스로 범위를 좁힌 API 키로 부르면 403이에요.

GET /v1/naver/keywords/history

키워드 하나의 측정 기록이에요. 실제로 측정한 날마다 한 점씩(캐시에서 나온 건 쌓이지 않아요), 최신순으로 검색량, 문서수, 월 발행량을 줘요. 기록이 없으면 200과 data: []가 와요.

GET /v1/research/youtube/search

검색어로 YouTube를 찾아 상위 영상의 정보를 줘요.

• 조회수, 구독자 수, 길이, 게시일은 YouTube가 준 그대로예요.
• 조회/구독 비율과 쇼츠/롱폼 구분은 포샌디가 계산한 값이고 YouTube 지표가 아니에요. dataNotes에 그렇게 적혀 있어요.
• 제목과 훅을 뽑는 붙여넣을 프롬프트를 그 사람의 포샌디 언어(한국어, 영어)로 줘요.
• 같은 검색은 24시간 캐시라 횟수에 안 세요. 새 검색은 사람당 하루 횟수(응답의 quota)와 공용 YouTube Data API 단위를 써요.
• 기록에 reportId로 저장돼요.

GET /v1/research/youtube/reports

저장된 YouTube 검색 기록을 최신순으로 줘요. 언제, 검색어와 필터, 주제, 영상 수, 캐시였는지가 와요. 최대 30일 보관하고 지워요.

GET /v1/research/youtube/reports/{id}

저장된 검색 하나를 그때의 영상 목록, 그 목록으로 만든 프롬프트와 함께 줘요.

POST /v1/naver/visibility/checks

키워드 10개까지를 그 사람의 포샌디 크롬 확장으로 네이버 통합검색에서 확인해요. 확장은 그 사람 브라우저에서 공개 검색 결과 페이지를 약 3초 간격으로, 쿠키와 창 없이 읽어요.

• 키워드마다 AI 브리핑이 답했는지와 형태, 본문과 이미지 출처의 순위, 출처별로 인용된 답변 문단 수, 검색 결과 안 블로그 글 위치, 관련 질문을 줘요.
• 202와 runId, waitMs를 주면 200과 결과가 와요.
• 사람당 하루 200페이지예요. 확장이 꺼져 있으면 503 bridge_offline이에요.
• 200 응답에는 citationRules도 와요. AI 브리핑이 인용한 글에서 포샌디가 측정한 문장 규칙(rules)과, 등급, 근거, 주의가 붙은 더 약한 제안(suggestions)이에요. 네이버의 기준이 아니라 포샌디가 측정한 값이에요.

GET /v1/naver/visibility/runs/{runId}

확인 하나의 상태(running, done, partial, failed), 돌아온 키워드 수, 요청한 순서대로의 결과, 아직 읽는 키워드(pending)를 줘요. 확인이 끝나면(done, partial, failed) 확인 응답과 같은 citationRules도 와요.

GET /v1/naver/visibility/runs

이 사람의 최근 확인 목록이에요. 최신순으로 종류, 키워드 수, 돌아온 수를 주고, 블로그를 넣었던 확인은 인용된 수와 노출된 수도 줘요.

POST /v1/naver/visibility/scan

블로그 성적표를 시작해요. 공개 RSS로 최근 글을 읽고, 글마다 대표 키워드를 골라 뒤에서 확인해요. 202와 runId, etaSeconds를 줘요. 같은 블로그의 6시간 안 성적표가 있으면 200과 reused: true로 답해요.

GET /v1/naver/visibility/blog

기록으로 만든 블로그 성적표예요.

• 숫자 카드: AI 인용률, 통합검색 노출률, AI 브리핑이 뜬 키워드 수, 인용된 글 수
• 오각형 축: 포샌디 기준 10점 만점 점수 다섯 개, 원값과 기준값이 같이 와요. 네이버 점수가 아니에요.
• 가장 먼저 할 일, 글별 대표 키워드와 마지막 판정, 카테고리, 추세, 사건

GET /v1/naver/visibility/posts/{blogId}/{logNo}

글 하나의 기록이에요. 지켜보는 글(대표 키워드와 그 출처), 그 키워드를 확인할 때마다 나온 그 글의 판정, 사건(인용, 노출이 시작되거나 빠진 때)을 줘요.

PATCH /v1/naver/visibility/posts/{blogId}/{logNo}

글의 대표 키워드(확인할 때 검색하는 말)를 바꿔요. 그 글의 기록으로 답해요.

GET /v1/naver/visibility/keywords

이 사람이 키워드 하나를 확인한 기록 전체예요. 최신순으로, 확인마다 AI 브리핑 출처와 검색 결과의 블로그 글을 줘요.

POST /v1/naver/seo/check

발행 전에 네이버 블로그 마크다운 본문의 배치 규칙을 검사해요. 발행을 막지는 않고, 무엇이 어긋났는지와 이유를 알려 줘요.

검사 항목은 이래요.

• 소제목과 서브 키워드가 1:1로 맞는지
• 메인 키워드가 3~5회 나오는지
• 태그 12~15개가 전부 본문에 있는지
• 첫 3단락에 상품 이름이 없는지
• 첨부 이미지가 전부 자리를 잡았고 캡션이 10자 이상인지
• 분량이 하한을 넘는지

응답에는 pentagon(같은 검사 다섯 개를 0~10점으로: 키워드, 구조, 분량, 사진, 태그)과 citation(AI 브리핑이 가져다 쓰는 문장 모양의 개수: 정의 문장, 조작 순서, 괄호 속 구체 값, 앞쪽의 정의, 링크 카드)이 같이 와요. 둘 다 참고용이고 발행을 막지 않아요.

POST /v1/naver/layout

발행 전에 본문이 어떻게 놓일지 미리 봐요. 발행할 때 기본으로 도는 재배치(layout: template)와 같은 계산을 아무것도 보내지 않고 돌려줘요. forms: "all"이면 모든 프리셋 결과를 한 번에 줘서 사람이 비교하고 고를 수 있어요.

GET /v1/naver/forms

기본으로 제공하는 글 폼 7개예요. 폼은 글의 짜임새를 정해요.

• 섹션을 무엇으로 시작하는지
• 인용을 소제목으로 쓰는지, 인용문으로 쓰는지
• 핵심 문장을 얼마나 자주 강조하는지
• 섹션마다 사진이 몇 장인지
• 사진에 캡션을 다는지

모두 실제로 올라간 글을 측정해서 만들었어요. 글을 만들 때 폼 id를 넣으면 돼요. 폼은 AI에게 무엇을 시킬지만 정하고, 발행 자체에는 영향이 없어요.

GET /v1/naver/drafts

네이버 블로그 임시저장함의 초안 목록이에요. draftOnly로 저장한 글과 네이버 에디터에서 손으로 저장한 글이 같이 나와요. 확장 0.7.2 이상이 필요해요.

POST /v1/naver/drafts/{logNo}/publish

임시저장함의 초안을 네이버에 있는 그대로 발행해요. 확장이 그 초안을 에디터에 불러와 발행 버튼을 누르기 때문에, 손으로 고친 내용이 그대로 나가요. 응답 모양은 POST /v1/posts와 같아요. 포샌디가 만든 초안이면 그 글 기록이 발행됨으로 바뀌어요. 올라간 뒤에 글을 고치려면 그 글에 update_post를 불러요. 지금 원문이 먼저 돌아와요.

답글과 반응 숫자는 답글과 지표, 파일 올리기는 미디어에서 이어서 봐요.