REST API

발행

올리고, 읽고, 다시 시도하고, 지웁니다.

GET/v1/posts

최근 발행. 최신순이고 답글은 목록에 안 섞입니다.

페이지 넘기기

이름타입설명
limitquery1-100, defaults to 20.
beforequeryA publish id from a previous page's nextBefore. Returns the ones older than it.
includeDeletedquerytrue brings back posts you deleted from the channel. They are hidden by default. Our record and its metrics stay either way.
statusqueryNarrow to one or more statuses, comma separated: scheduled, draft, publishing, published, partial, failed or cancelled. Omit for everything, scheduled and draft included.
sincequeryYYYY-MM-DD or ISO 8601 with a four-digit year. Posts dated at or after this. A scheduled post is dated by scheduledAt, a sent one by when it was created. A value that is not a real date, or a year past 9999, is refused with invalid_params.
untilqueryYYYY-MM-DD or ISO 8601 with a four-digit year. Posts dated at or before this; a date means the whole day. A value that is not a real date, or a year past 9999, is refused with invalid_params.
sortqueryscheduled orders by the post's date ascending and drops paging. Omit for newest first.
hasMoreresponseThe list was cut short.
nextBeforeresponsePass it back as before. Absent when there is nothing more.

POST/v1/posts

연결된 계정 하나 이상에 올립니다.

이름타입설명
content필수stringPost text. Emoji count as UTF-8 bytes.
accountIds필수string[]Ids from GET /v1/accounts.
mediaIdsstring[]Media already confirmed with complete. On Naver Blog you may leave out ids the body already points at with media:<id>; we read those from the text and attach them.
optionsobjectPer-channel settings, keyed by the channel id. The shape is in GET /v1/platforms under options and on each channel page. Some channels cannot publish without it — YouTube needs options.youtube.title and Naver Blog needs options.naver_blog.title plus a category. Every channel takes options.<channel>.content, a different text for that channel alone.
scheduledAtstringISO 8601 with a timezone offset, 10 minutes to a year out. We keep the post as scheduled and send it at that time, on every channel.
draftbooleantrue saves the post without sending. It can have no accountIds yet. Send it later with POST /v1/posts/{id}/publish.
batchIdstringOptional tag, up to 40 characters, to group posts made together (for example the same text sent to two workspaces). Comes back on every post.
replyTostringThe post or reply to answer: its id on the channel, our publish id (post_…), or a link to the post. A publish id or a link becomes that post's id on the replying account's channel, so send one account per request. A Threads, Instagram, Facebook or Bluesky link works only for a post we have on record.
threadItemsobject[]Split a long post into a chain: [{ content, mediaIds? }]. The first item is the root, the rest become replies under it in order. Each item obeys the character limit on its own. Exclusive with content. Only Threads, Bluesky and X take a chain; the composer builds one with the item editor. If a later item fails the ones already up stay up, and the response carries thread.resumeFrom. If an item fails, the later items on that account close as failed with errorCode thread_broken, and retry_post continues from the item that failed. Posts that have later items carry them back as threadItems, and PATCH takes the same field while the post is scheduled or a draft.
topicTagstringOne topic to tag the post with. Threads takes exactly one and rejects periods and ampersands. On a thread it applies to the first piece only. This top-level field is an alias: if a channel in the call does not take topics, the whole call is refused. To tag only the Threads part, use options.threads.topicTag.
Idempotency-KeyheaderSend the same key when you retry and we return the first answer instead of publishing twice. Reusing a key with a different body is a 422. Kept for 24 hours.
waitbooleanHold the response until the post is really out. Text waits up to 10 seconds, media up to 75. Past that you get the usual 202 with a next hint, and the post keeps going. Defaults to false.
curl -X POST https://api.uplika.com/v1/posts \
  -H "authorization: Bearer $UPLIKA_KEY" \
  -H "content-type: application/json" \
  -d '{
    "content": "Now with images",
    "accountIds": ["acc_01H..."],
    "mediaIds": ["med_01H..."]
  }'

GET/v1/posts/{id}

발행 하나와 대상별 상태.

대상 상태

이름타입설명
publishingstatusIn flight at the channel.
publishedstatusCarries externalId and url. If the account was disconnected afterwards, the target stays published with connectionId null and accountHandle set to that account's handle until the same account is reconnected.
partialstatusSome channels went out and some did not. Retry sends only the ones that failed. There is no 207 — publishing is 202 plus polling, so nothing is held open.
cancelledstatusDeleted from the channel. Our record and its metrics stay. Hidden from GET /v1/posts unless you pass includeDeleted=true.
failedstatusCarries error.
scheduledstatusHeld until scheduledAt. Nothing is on any channel yet. Editable.
draftstatusSaved without a time. May have no targets. Editable.

발행 하나에 채널마다 행이 하나입니다. publishing 은 진행 중, published 는 채널의 id 와 주소를 들고 있고, failed 는 사유를 들고 있습니다.

X 글에 든 돈

X 대상 행에만 billing: { operation, mills, state, balanceMills } 가 실립니다. operation 은 post, 링크가 든 글이면 post_url, 답글이면 reply 이고 체인의 둘째 토막부터가 답글입니다. mills 는 그 글에 X 크레딧에서 든 금액이고 1/1000 달러 단위이며 첨부 파일과 대체 텍스트까지 포함합니다. state 는 나가는 동안 reserved, X 가 받으면 confirmed, 되돌렸으면 released 입니다. balanceMills 는 그 사람의 지금 X 크레딧 잔액입니다. 글 하나를 주는 응답(GET /v1/posts/{id}, GET /v1/posts/{id}/thread 의 post)과 발행 응답에 실리고 목록 엔드포인트에는 안 실립니다. 잔액이 글을 감당하지 못하면 발행은 topUpUrl 과 함께 402 x_credits_insufficient 로 답하고 아무것도 나가지 않습니다.

{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 · /v1/engagement/like 에 보냅니다. 업리카의 유튜브 하루 한도가 다 찬 날의 유튜브 링크는 429 youtube_quota_exhausted 입니다. POST /v1/posts 의 replyTo 도 발행 id 와 링크를 받고, 답글을 다는 계정의 채널에서 그 글이 받은 id 로 바꿔 보냅니다. 스레드 · 인스타그램 · 페이스북 · 블루스카이 링크는 우리 기록에 있는 글만 됩니다. 링크와 채널이 준 글 id 는 한 채널의 사본을 가리키는데 DELETE 와 나간 글의 수정(PATCH)은 그 글이 나간 모든 채널에 닿습니다. 그 글이 다른 채널에도 있으면 postId · channels 와 함께 409 post_spans_channels 로 답하고 아무것도 바꾸지 않습니다. 모든 채널에 하려면 그 postId 로 다시 부르세요.

예약과 초안

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 를 받습니다. 있으면 그 채널에만 공통 본문 대신 나가고, 길이·미디어 검사도 그 본문으로 합니다. 스레드 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 과 함께 다시 보내면 같은 주소에 다시 씁니다. 네이버에 있는 사진과 서식이 그대로 남습니다. 업리카로 낸 네이버 글도 올린 사진 파일이 정리된 뒤(나간 지 하루쯤)에는 같은 길입니다. 옵션만 고치면 바로 나가고, 본문을 고치면 지금 원문이 먼저 옵니다.

이름타입설명
contentstringNew post text.
accountIdsstring[]New target accounts. Replaces the current set.
mediaIdsstring[]New media, in order. Replaces the current set. On a post going only to Naver Blog, leave it out when the body places media with media: references: those references become the list and media the new body does not place is removed (the response note says how many).
optionsobjectPer-channel settings. Replaces the whole object.
scheduledAtstringNew send time, same rules as on create. null turns the post into a draft.
draftbooleantrue turns a scheduled post, or a Naver Blog post still waiting for the browser extension, back into a draft.

POST/v1/posts/{id}/publish

예약·초안 글을 지금 보냅니다. 예약 크론과 같은 함수라 두 번 나가지 않습니다.

이름타입설명
waitbooleanHold the response until the post is really out, same as on create.

POST/v1/posts/{id}/retry

실패한 대상만 다시 시도합니다. 이미 나간 대상은 건너뜁니다. 네이버 임시저장 직후 끊긴 대상(naver_draft_unknown)이나 제때 확인되지 않은 네이버 답글(naver_reply_unknown), 사이트가 확인해 주지 않은 워드프레스 글(wordpress_publish_unconfirmed), 등록을 눌렀는데 클립 목록에서 확인되지 않은 네이버 클립(clip_unconfirmed, 클립 크리에이터 콘텐츠를 먼저 확인), 보낸 뒤 쓸 만한 답을 못 받은 X 글(x_publish_unknown, X 계정을 먼저 확인), 보낸 뒤 틱톡이 답하기 전에 연결이 끊긴 틱톡 글(tiktok_publish_unknown, 틱톡 프로필을 먼저 확인), 올라갔는데 가져온 사본이 쥐고 있는 글(published_as_imported_copy, 그 사본을 쓰기), 채널이 답하기 전에 멈춘 대상(publish_outcome_unknown, 그 채널을 먼저 확인하고 있으면 다른 채널은 새 글로)이 있으면 본문에 {"force": true} 를 실어야 다시 보냅니다. 같은 계정에 같은 글과 같은 파일의 다른 글이 이미 있으면(다시 올린 같은 파일도 같은 파일로 봅니다) 그 글의 id 와 함께 409 duplicate_post 로 답하고 아무것도 다시 보내지 않습니다. {"force": true} 면 그래도 보냅니다.

DELETE/v1/posts/{id}

글이 나간 모든 채널에서 지우고 우리 기록도 삭제로 표시합니다.

예약·초안 글은 채널에 아무것도 없으므로 DELETE 가 우리 기록을 지웁니다. 나간 글은 그 글이 나간 모든 채널에서 먼저 지우고 우리 기록은 지운 것으로 표시해 남깁니다. 링크나 채널이 준 글 id 로 불렀는데 그 글이 다른 채널에도 있으면 DELETE 는 어느 채널도 부르지 않고 postId · channels 와 함께 409 post_spans_channels 로 답합니다. 그 postId 로 같은 호출을 보내면 모든 채널에서 지웁니다. 채널의 휴지통이 꺼져 있어 글이 아주 지워지면 응답에 note(그대로 전할 문장)와 permanentlyDeleted(채널 이름)가 붙습니다. 네이버 임시저장 글은 그 브라우저에서 확장의 차례가 와야 지워집니다. 60초 안에 못 끝나면 응답에 그렇다고 말하는 note 가 붙고, 확장이 30분 안에 마저 지웁니다.

X 에서 글을 지우면 X 의 삭제값이 그 사람의 X 크레딧에서 빠집니다. 잔액이 모자라면 DELETE 는 topUpUrl 과 함께 402 x_credits_insufficient 로 답합니다. 잔액은 어느 채널도 부르기 전에 보므로 아무것도 지워지지 않습니다. 그 사이 다른 호출이 잔액을 먼저 썼다면 이미 지운 채널을 문장이 적습니다.

채널에 이미 있는 것 읽기

우리 기록에는 우리를 거쳐 나간 것만 있습니다. 아래 넷은 채널 자체를 읽고, 어디에 올릴지를 고릅니다. list_channel_posts · get_quota · open_post · select_channels 뒤에 있는 라우트라 REST 로도 같은 답을 받습니다.

GET/v1/posts/{id}/thread

글 하나와 댓글·지표를 한 번에 받습니다.

이름타입설명
accountIdqueryWhich channel's copy to read, on a post that went to more than one channel. Omit and the answer says which copy it read.

GET/v1/channels/posts

앱에서 직접 쓴 글까지, 지금 채널에 있는 것.

쿼리

이름타입설명
accountIdqueryLimit to one connected account. Omit to cover every channel.
limitquery1-100, defaults to 25.

GET/v1/channels/quota

24시간 한도를 채널이 얼마나 썼다고 말하는지. X 계정이 들어 있으면 응답에 xCredits: { balanceMills, topUpUrl } 도 실립니다. 그 사람이 미리 산 X 크레딧 잔액(1/1000 달러 단위, 산 적이 없으면 0)과 충전할 곳입니다.

GET/v1/channels/bridge

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

GET/v1/channels/publish-options

발행 전에 채널에 물어봐야 하는 것. TikTok 전용이다. 어느 닉네임으로 나가는지, 이 계정이 지금 고를 수 있는 공개 범위, 올릴 수 있는 상태인지, 영상 길이 상한을 준다. 다른 채널은 not_supported 다.

이름타입설명
accountIdqueryRequired. These values are per connected account and change when the person edits their channel settings, so do not cache them.

GET/v1/channels/instagram/audio

인스타그램 계정 하나가 릴스에 붙일 수 있는 음악과 원본 소리. options.instagram.audio 에 넣는다. 인스타그램 전용이고 Facebook 경유로 연결한 계정만 된다. query 가 없으면 그 계정의 인기 목록이고, query 가 있으면 음악은 메타의 로열티 프리 음악(Sound Collection)에서만 찾는다. 그래서 가수나 곡 이름으로는 그 곡이 안 나온다. 정렬 · 날짜 조건과 릴스 수 · 만든 날짜가 없고, 검색어는 띄어쓰기까지 맞아야 하며, 인기 목록의 가요에는 음원 파일이 없다.

이름타입설명
accountIdqueryRequired. A connected Instagram account. Trending audio differs per account, so use ids from the same account's results.
typequerymusic (default) or original_sound.
queryqueryOptional, up to 100 characters. Without it you get this account's trending audio. With type music it searches royalty-free music from Meta's Sound Collection only. Matching is strict about spelling and spacing.
limitquery1-50, defaults to 25.
cursorquerynextCursor from the previous page, unchanged.

POST/v1/accounts/select

연결된 채널 중 어디에 올릴지 고릅니다.

POST/v1/accounts/:id/refresh

채널 메타데이터(네이버 블로그 카테고리 · 핀터레스트 보드 등)를 다시 읽습니다. 브라우저 확장을 최대 1분 기다립니다.

이름타입설명
scopestring | string[]Omit to list candidates. "all" for every active channel, or an array mixing platform names, handles and account ids.

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

글이 options.pinterest.boardId 를 비웠을 때 핀을 올릴 핀터레스트 기본 보드를 정합니다. 연결의 보드 목록에 있는 보드만 받습니다. 연결한 뒤에 만든 보드는 refresh 를 먼저 부릅니다.

이름타입설명
boardIdstringRequired. A board id from the account's pinterest.boards in GET /v1/accounts. Answers with the account, pinterest.defaultBoardId updated.

GET/v1/naver/blog/diagnose

네이버 블로그의 공개 RSS(최근 글, 최대 50편)를 읽어 제목이 검색을 노리고 있는지 잽니다. 검색 의도어(가격 · 방법 · 후기)가 든 제목의 비율, 날짜 · 회차로 시작하는 제목 수, 한 달 글 수, 카테고리, 제목에 반복되는 말(조사에 넣어 볼 후보이지 검색되는 키워드가 아닙니다)을 돌려줍니다. 읽은 날짜 범위를 같이 주므로 뜸한 블로그의 50편을 전부로 오해하지 않습니다. 사용자 무관 24시간 캐시이고, 캐시 미스만 사람당 하루 20회를 씁니다. 네이버 API 키가 필요 없습니다.

이름타입설명
blog필수stringA Naver blog id (2-40 letters, digits, - or _) or any link to the blog: blog.naver.com/<id>, m.blog.naver.com/<id>/<logNo>, PostView.naver?blogId=<id>.

POST/v1/naver/keywords/judge

네이버 검색 키워드를 재고 글 하나에 쓸 세트를 고릅니다. 펼치지는 않으니 갖고 있는 키워드를 보내세요. 월간검색수(검색광고)·블로그 문서수·월 발행량(API HUB)·키워드별 판정·같은 의도의 메인 1 + 서브 2~5 세트를 돌려줍니다. 결과는 사용자 무관 7일 캐시이고, 사용자당 하루 60회·600 키워드입니다.

이름타입설명
keywordsstring[]Required. 1-300 keywords. Spaces are fine; the numbers come back per keyword as you sent it.
savebooleanDefault false. true stores this research as a report (the keywords, the first set's main and subs, every set with its prompt) and returns reportId. The same person sending the same keyword set within ten minutes gets the existing reportId back with no new row and no judge call spent.
seedTextstringWhat the person typed, kept with the saved report as its label. Defaults to the first five keywords.
cacheOnlybooleanDefault false. true never calls Naver: keywords without a fresh cached value come back in unmeasured with no numbers. Use it after measuring in chunks, so the judge call is instant and spends nothing upstream.
budgetMsnumberTime budget for new measurements, default and maximum 60000. When it runs out, no new upstream call starts; the response says partial: true and lists unmeasured. Call again and the cached part is skipped.

POST/v1/naver/keywords/measure

판정·세트 없이 측정만. withDocs:false 면 문서수를 건너뜁니다.

이름타입설명
keywordsstring[]Required. 1-300 keywords. At most 40 of them are measured fresh in one call; the rest come back in unmeasured and are picked up by the next call.
withDocsbooleanDefault true. false measures search volume only.
budgetMsnumberTime budget for new measurements, default and maximum 60000. Past it the call stops starting upstream requests and returns partial: true with unmeasured.

POST/v1/naver/keywords/expand

에이전트 · API 키를 위해 네이버 자동완성으로 씨앗 키워드를 1단계 펼칩니다 (대시보드는 브라우저에서 합니다). 그 사람의 업리카 크롬 확장이 켜져 있으면 확장이 그 사람 인터넷으로 창 없이 받고, 아니면 서버가 받습니다. 찾은 단어와 어느 씨앗에서 나왔는지, 그리고 어느 길로 받았는지(via)를 돌려줍니다. 둘 다 못 하면 503 naver_autocomplete_unavailable 이고, 그때는 키워드 목록을 직접 judge 에 넘기면 됩니다.

이름타입설명
seedsstring[]Required. 1-10 seed keywords. Each is sent to Naver autocomplete once (one level); the words that come back are candidates to measure with judge, not proven keywords. Cached seven days across users. No daily quota: when the person's uplika Chrome extension answers there is no wait, and when our server answers, one call per person every 60 seconds (naver_autocomplete_busy with retryAfterSeconds).

돌려주는 것

이름타입설명
found{ keyword, from }[]Every word, the seeds first. from is seed, or L1:<seed> for a word that seed produced.
errors{ query, error }[]Seeds that could not be looked up, with why.
cachednumberHow many seeds came from the seven-day cache.
via{ cache, extension, server }How many seeds each path answered: the shared cache, the person's Chrome extension (in the background, from their own connection), or our server.

GET/v1/naver/keywords/reports

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

이름타입설명
limitnumberDefault 50, newest first.

GET/v1/naver/keywords/history

키워드 하나의 측정 시계열입니다. 실제로 잰 날마다 한 점(캐시 적중은 안 쌓입니다), 최신 먼저, 검색량 · 문서수 · 월 발행량. 빈 목록은 200 에 data: [] 입니다.

이름타입설명
keyword필수stringThe keyword, as you would send it to measure. A query parameter, since keywords are usually Korean.
limitnumberDefault 100 days, newest first.
tznumberThe viewer's time zone offset in minutes, with the sign of JavaScript getTimezoneOffset (Korea is -540). Measurements fold into that zone's days. Default 0 (UTC).
이름타입설명
q필수stringThe search words, as a viewer would type them.
orderstringviewCount (default), date or relevance.
periodstring7d, 1m, 3m, 6m or 1y. Omit for no limit.
formatstringall (default), shorts or long. 60 seconds or less counts as a Short.
maxnumber1-50, default 25.
topicstringThe video the person wants to make, one line. Goes into prompt and is saved with the report.

GET/v1/research/youtube/reports

저장된 유튜브 검색 기록을 최신순으로 줍니다. 언제, 검색어와 필터, 주제, 영상 몇 편, 캐시였는지. 최대 30일 보관하고 지웁니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

이름타입설명
limitnumberDefault 50, newest first.

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

저장된 검색 하나를 그때의 영상 목록과 거기서 만든 프롬프트와 함께 줍니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

POST/v1/google/keywords/research

사람이 고른 나라에서 키워드 최대 10개의 구글 검색량을 줍니다. 월 평균 검색량, 최근 12개월, 광고 경쟁, 상단 입찰가와 같은 숫자를 단 연관 키워드입니다. 입찰가는 bidCurrency 에 적힌 업리카 구글 광고 계정의 통화이고, 나라와 상관없이 같으며 환산하지 않은 값입니다. 검색량은 구글이 눈금으로 묶은 어림값입니다. 구글에 데이터가 없는 키워드는 noData 에 나오고 0 이 아닙니다. 키워드는 한 검색에 모읍니다. 쉼표로 이어 붙인 문자열도 됩니다. 같은 검색은 7일 캐시이고, 사람당 하루 횟수는 없습니다. 베타라 사람이 API 키에 대해 끌 수 있습니다.

이름타입설명
keywords필수string[]1 to 10 keywords, as the person wrote them. A comma-separated string or an item with commas is split into keywords.
country필수stringTwo-letter country code such as KR or US. Required, with no default. Ask the person which country they mean.
languagestringLanguage code such as ko or en. Leave it out to use the country's main language.
maxnumberHow many related keywords to return, biggest first. 1-200, default 50.
이름타입설명
qstringKeywords, as a viewer would search them, up to 100 characters. Pass q or advertiserId, not both.
advertiserIdstringA Facebook page id from /v1/research/ads/advertisers. Lists that advertiser's ads instead of searching words.
countrystringTwo-letter code of the country the ads were shown in. Default KR.
statusstringactive (default), inactive or all.
mediastringall (default), image or video.
sortstringimpressions (default) or relevance. There is no newest-first sort; narrow with from and to instead.
fromstringOnly ads that started on or after this date, YYYY-MM-DD.
tostringOnly ads that started on or before this date, YYYY-MM-DD.
exactbooleanDefault false. true keeps only ads with the exact phrase.
koreanOnlybooleanDefault true. Drops ads without Korean text, since country KR means ads shown in Korea and foreign ones are mixed in. received and kept say how many were dropped.
cursorstringThe cursor from the previous page.

GET/v1/research/ads/advertisers

광고주 이름에 맞는 페이스북 페이지를 메타 광고 라이브러리에서 찾아 인증된 페이지 먼저, 그다음 좋아요 순으로 줍니다. pageId, 분류, 좋아요, 인스타그램 핸들이 듭니다. 같은 이름의 페이지가 여럿인 일이 잦으니 사람이 고르게 한 뒤 그 pageId 를 검색의 advertiserId 로 넘깁니다. 하루 횟수를 하나 쓰고, 같은 이름은 24시간 캐시라 횟수를 안 씁니다.

이름타입설명
q필수stringA brand or page name, up to 100 characters.

GET/v1/research/ads/{adId}/transcript

영상 광고의 대사를 adId(검색 결과에서 hasVideo 가 true 인 광고)로 읽습니다. 영상이 없거나 말소리가 없거나 2분보다 길거나 제공처가 그 영상을 읽지 못하면 available 이 false 입니다. 30일 저장하고, 새로 읽을 때만 하루 횟수를 하나 씁니다.

GET/v1/research/ads/reports

저장된 광고 검색 기록을 최신순으로 줍니다. 언제, 키워드인지 광고주인지, 나라, 광고 몇 개, 캐시였는지. 광고 본문은 7일(썸네일 링크는 그보다 먼저 만료), 기록 줄은 30일 보관합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

이름타입설명
limitnumberDefault 50, newest first.

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

저장된 광고 검색 하나를 그때의 광고 목록과 함께 줍니다. 7일이 지나면 resultsExpired 가 true 이고 ads 는 null 이니 다시 검색합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

이름타입설명
domainstringA website host such as oliveyoung.co.kr, up to 253 characters. A pasted address is reduced to its host. Pass domain or advertiserId, not both.
advertiserIdstringA Google advertiser id (AR followed by digits) from /v1/research/google-ads/advertisers or from an ad's advertiser.id.
regionstringTwo-letter code of the country the ads were shown in. Default KR.
platformstringall (default), search, youtube, shopping, maps or play.
formatstringall (default), text, image or video.
fromstringOnly ads shown at any time on or after this date, YYYY-MM-DD.
tostringOnly ads shown at any time on or before this date, YYYY-MM-DD.
cursorstringThe cursor from the previous page.

GET/v1/research/google-ads/advertisers

브랜드나 회사 이름에 맞는 광고주를 구글 광고 투명성 센터에서 찾아 광고 수 추정(adsEstimate)이 큰 순서로 주고, 맞는 웹사이트는 domains 로 줍니다. 구글은 등록한 회사 · 계정마다 광고주를 따로 두어 한 브랜드에 여럿인 일이 잦으니 사람이 고르게 한 뒤 그 advertiserId 를 검색에 넘깁니다. 브랜드 이름이 회사 이름과 다르면 0곳일 수 있으니 법인 이름이나 웹사이트로 찾습니다. 하루 광고 분석 횟수를 하나 쓰고, 같은 이름은 24시간 캐시라 횟수를 안 씁니다.

이름타입설명
q필수stringA brand or company name, up to 100 characters.
regionstringTwo-letter country code to search advertisers in. Default KR.

GET/v1/research/google-ads/reports

저장된 구글 광고 조회 기록을 최신순으로 줍니다. 언제, 웹사이트인지 광고주인지, 나라, 광고 몇 개, 캐시였는지. 메타 광고 검색은 이 목록에 없습니다. 광고 본문은 7일, 기록 줄은 30일 보관합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

이름타입설명
limitnumberDefault 50, newest first.

GET/v1/research/google-ads/reports/{id}

저장된 구글 광고 조회 하나를 그때의 광고 목록과 함께 줍니다. 7일이 지나면 resultsExpired 가 true 이고 ads 는 null 이니 다시 조회합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

POST/v1/naver/visibility/checks

키워드 10개까지를 그 사람의 업리카 크롬 확장으로 네이버 통합검색에서 확인합니다. 확장은 그 사람의 브라우저에서 공개 검색 결과 페이지를 3초쯤 간격으로, 쿠키 · 창 없이 읽습니다. 키워드마다 AI 브리핑이 답했는지와 형태, 본문 · 이미지 출처의 순위와 출처마다 인용한 답변 문단 수, 검색 결과의 블로그 글 자리, 관련 질문을 냅니다. 202 와 runId, waitMs 를 주면 200 과 결과입니다. 사람당 하루 200 페이지이고 확장이 꺼져 있으면 503 bridge_offline 입니다. 200 응답에는 citationRules 도 실립니다. AI 브리핑이 인용한 글에서 업리카가 잰 문장 규칙(rules)과, 등급 · 근거 · 주의가 붙은 더 약한 제안(suggestions)입니다. 네이버 기준이 아니라 업리카가 잰 것입니다. blogTab: true 면 키워드마다 블로그 탭(관련도순) 1쪽도 읽어 blogTab 과 verdict.blogTabRank(그 쪽 블로그 글 사이 내 블로그의 자리)를 주고, 키워드마다 2 페이지를 씁니다. 확인은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.

이름타입설명
keywords필수string[]1-10 keywords, as a reader would search them.
blogstringA Naver blog id or any link to the blog. Its posts are marked mine: true and each result carries verdict (bodyRank, imageRank, citedParagraphs, organicRank, organicArea, cited, exposed).
freshbooleanDefault false. A keyword this person read in the last 30 minutes comes back from the saved result; true reads it again and spends the daily allowance.
blogTabbooleanDefault false. true also reads page 1 of the blog tab sorted by relevance for each keyword: each result carries blogTab (read, sort, size, top 5 posts, reason, requiredVersion when the extension is too old) and, with blog, verdict.blogTabRank. Two search pages per keyword from the daily allowance. A saved result from the last 30 minutes is reused only if its blog tab was read.
waitMsnumberHold the response up to this many milliseconds (at most 60000) and answer 200 with the results so far; partial: true with pending lists what the extension is still reading in the background. Without it the answer is 202 with runId.

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

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

GET/v1/naver/visibility/runs

이 사람의 최근 확인입니다. 최신 먼저, 종류 · 키워드 수 · 돌아온 수, 블로그를 줬으면 인용 · 노출된 수.

이름타입설명
limitnumberDefault 20, at most 50, newest first.

POST/v1/naver/visibility/scan

블로그 성적표를 시작합니다. 공개 RSS 로 최근 글을 읽고 글마다 대표 키워드를 골라 백그라운드로 확인합니다. 202 와 runId · etaSeconds, 같은 블로그의 6시간 안 성적표는 200 과 reused: true 입니다.

이름타입설명
blog필수stringA Naver blog id or any link to the blog.
limitnumberHow many recent posts, 1-30, default 20.

GET/v1/naver/visibility/blog

기록으로 만든 블로그 성적표입니다. 숫자 카드(AI 인용률 · 통합검색 노출률 · AI 브리핑이 뜬 키워드 수 · 인용된 글 수), 오각형 축(업리카 기준 10점 만점 다섯, 원값 · 기준값과 함께. 네이버 점수가 아닙니다), 제일 먼저 할 것, 글별 대표 키워드와 마지막 판정, 카테고리, 추세, 사건.

이름타입설명
blog필수stringA Naver blog id or any link to the blog.
tznumberThe viewer's time zone offset in minutes, with the sign of JavaScript getTimezoneOffset (Korea is -540). The trend groups checks into that zone's days. Default 0 (UTC).

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

글 하나의 기록입니다. 지켜보는 글(대표 키워드와 그 출처), 그 키워드의 확인마다 그 글의 판정, 사건(인용 · 노출 시작과 빠짐).

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

글의 대표 키워드(확인이 검색하는 말)를 고칩니다. 그 글의 기록으로 답합니다.

이름타입설명
mainKeyword필수string1-100 characters. Used from the next check on; the post's old verdict is cleared.
titlestringThe post title, used only when the post is not tracked yet (up to 300 characters).

GET/v1/naver/visibility/keywords

이 사람이 한 키워드를 확인한 기록 전부입니다. 최신 먼저, 확인마다 AI 브리핑 출처와 검색 결과의 블로그 글.

이름타입설명
keyword필수stringThe keyword, up to 100 characters. A query parameter, since keywords are usually Korean.
blogstringMark that blog's posts and add a verdict to each check.
limitnumberDefault 30, at most 100, newest first.

POST/v1/naver/seo/check

발행 전에 네이버 블로그 마크다운 본문의 배치 규칙을 잽니다. 소제목 = 서브 키워드 1:1, 메인 3~5회, 태그 12~15개 전부 본문에, 첫 3단락에 상품 이름 없음, 첨부 이미지 전부 자리 잡고 캡션 10자 이상, 분량 하한. 막지는 않고 무엇이 어긋났는지와 이유를 말합니다. 응답에는 `pentagon`(같은 게이트 다섯을 0~10 점수로: 키워드 · 구조 · 분량 · 사진 · 태그)과 `citation`(AI 브리핑이 가져다 쓴 문장 모양의 개수: 정의 문장 · 조작 순서 · 괄호 속 구체 값 · 앞쪽의 정의 · 링크 카드)이 같이 옵니다. 둘 다 정보일 뿐 막지 않습니다.

이름타입설명
contentstringRequired. The Markdown body, up to 60,000 characters.
titlestringThe post title.
mainstringThe main keyword. Without it the keyword checks cannot pass.
subsstring[]Sub keywords, one per section title.
tagsstring[]The tags you will send in options.naver_blog.tags.
fixedTagsstring[]Tags that need not appear in the body (brand tags).
productsstring[]Product and brand names that must stay out of the first three paragraphs.
mediaIdsstring[]The media ids attached to the post, to check that each is placed.

POST/v1/naver/layout

발행 전에 본문이 어떻게 놓일지 봅니다. 발행이 기본으로 도는 재배치(layout: template)와 같은 계산을 아무것도 보내지 않고 돌려주고, forms: "all" 이면 프리셋 전부의 결과를 한 번에 줘서 사람이 고를 수 있습니다.

이름타입설명
content필수stringThe markdown body to lay out.
mediaIdsstring[]Attached media, in order. Images the body does not reference are placed by the form.
formstringOne preset id (default photo-story). Ignored when forms is given.
forms"all" | string[]Lay the same body out in several presets at once; the response carries layouts[] so a person can compare and pick.

GET/v1/naver/forms

기본으로 드리는 글 폼 일곱 개입니다. 폼은 글의 결입니다 — 섹션을 무엇이 여는지, 인용이 제목인지 인용문인지, 핵심 문장을 얼마나 자주 강조하는지, 섹션마다 사진이 몇 장인지, 사진에 캡션을 다는지. 전부 실제로 발행된 글에서 재서 만들었습니다. 생성할 때 id 를 주면 됩니다. 폼은 모델에게 무엇을 시킬지만 정하고 발행에는 닿지 않습니다.

GET/v1/naver/drafts

네이버 블로그 임시저장함의 초안 목록입니다. draftOnly 로 저장한 글과 네이버 에디터에서 손으로 저장한 글이 같이 나옵니다. 확장 0.7.2 부터입니다.

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

임시저장함의 초안을 네이버에 있는 그대로 발행합니다. 확장이 그 초안을 에디터에 실어 발행 버튼을 누르므로 손으로 고친 내용이 그대로 나갑니다. 응답 모양은 POST /v1/posts 와 같고, 그 초안이 업리카가 만든 것이면 그 글 기록이 발행됨으로 바뀝니다. 발행된 뒤에 글을 고치려면 그 글에 update_post 를 부르세요. 지금 원문이 먼저 돌아옵니다.

이름타입설명
logNo필수stringThe draft's id from GET /v1/naver/drafts.
accountIdstringRequired only when the workspace has more than one Naver Blog account.
title / categoryId / category / tags / openTypestringOverride the draft's own values. Left out, the draft goes out as it is.
waitbooleanHold until the extension finishes, up to 75 seconds like a post with media on POST /v1/posts. Past that you get the usual 202 with a next hint, and the draft keeps going out.

GET/v1/naver/grammar

네이버 블로그 본문이 알아듣는 문법입니다. 지시문·블록·인라인·속성·형광펜·미디어 참조와 상한을 담습니다. describe_grammar 도구가 돌려주는 것과 같은 안내이고 값이 한 곳에서 나오므로 에디터가 실제로 받는 것과 어긋나지 않습니다. topic 을 주면 한 절만 읽습니다.

이름타입설명
topicstringOne section instead of the whole guide. The 400 lists the ids.

POST/v1/naver/forms/extract

공개된 네이버 블로그 글을 읽어 그 결을 돌려줍니다. 짜임과 서식만 가져오고 글이나 사진은 가져오지 않습니다. 「이 글처럼 써줘」 에 씁니다. 읽은 결과를 저장해 두므로 AI 생성은 그 폼을 쓰고 네이버를 다시 부르지 않습니다. 레퍼런스가 바뀐 것을 반영하려면 다시 부르세요.

이름타입설명
urlstringRequired. A public Naver Blog post, like https://blog.naver.com/someone/224349824125. Only blog.naver.com links work, and private or deleted posts are refused. Five per minute.

GET/v1/naver/forms/snapshot

레퍼런스 글을 언제 읽었는지와 그때 블록 · 사진 수를 줍니다. 저장본만 읽고 네이버를 부르지 않습니다.

이름타입설명
urlstringRequired. The same post link you passed to extract. Answers from our database only; Naver is not called. 404 reference_not_read when it was never read.
publishing ──► published     the channel accepted it, permalink is set
           └─► partial       some channels made it, some did not
           └─► failed        none of them made it, error says why

failed     ──► publishing   retry, and only the targets that failed go again
published  ──► cancelled    you deleted it; our record and its metrics stay

자주 묻는 것

여러 채널에 한 번에 올리려면요?

accountIds 에 다 적어서 한 번만 부르면 됩니다. 요청 하나가 발행 하나를 만들고 채널마다 행이 하나씩 붙어서, 결과를 여러 호출에 걸쳐 맞춰 볼 필요가 없습니다.

202 는 무슨 뜻인가요?

글을 받았고 채널은 아직 대답하지 않았다는 뜻입니다. 무엇이 올라갔는지는 대상별 상태를 봐야 알고, 맨 위 응답은 일이 시작됐다는 것만 말합니다.

올라간 글을 지울 수 있나요?

됩니다. 채널에서 지우고 우리 기록은 삭제로 표시합니다. 그래서 그 글이 있었다는 것과 언제 나갔는지는 기록에 남습니다.