REST API
발행
올리고, 읽고, 다시 시도하고, 지웁니다.
GET/v1/posts
최근 발행. 최신순이고 답글은 목록에 안 섞입니다.
페이지 넘기기
| 이름 | 타입 | 설명 |
|---|---|---|
limit | query | 1-100, defaults to 20. |
before | query | A publish id from a previous page's nextBefore. Returns the ones older than it. |
includeDeleted | query | true brings back posts you deleted from the channel. They are hidden by default. Our record and its metrics stay either way. |
status | query | Narrow to one or more statuses, comma separated: scheduled, draft, publishing, published, partial, failed or cancelled. Omit for everything, scheduled and draft included. |
since | query | YYYY-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. |
until | query | YYYY-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. |
sort | query | scheduled orders by the post's date ascending and drops paging. Omit for newest first. |
hasMore | response | The list was cut short. |
nextBefore | response | Pass it back as before. Absent when there is nothing more. |
POST/v1/posts
연결된 계정 하나 이상에 올립니다.
| 이름 | 타입 | 설명 |
|---|---|---|
content필수 | string | Post text. Emoji count as UTF-8 bytes. |
accountIds필수 | string[] | Ids from GET /v1/accounts. |
mediaIds | string[] | 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. |
options | object | Per-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. |
scheduledAt | string | ISO 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. |
draft | boolean | true saves the post without sending. It can have no accountIds yet. Send it later with POST /v1/posts/{id}/publish. |
batchId | string | Optional tag, up to 40 characters, to group posts made together (for example the same text sent to two workspaces). Comes back on every post. |
replyTo | string | The 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. |
threadItems | object[] | 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. |
topicTag | string | One 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-Key | header | Send 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. |
wait | boolean | Hold 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}
발행 하나와 대상별 상태.
대상 상태
| 이름 | 타입 | 설명 |
|---|---|---|
publishing | status | In flight at the channel. |
published | status | Carries 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. |
partial | status | Some 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. |
cancelled | status | Deleted from the channel. Our record and its metrics stay. Hidden from GET /v1/posts unless you pass includeDeleted=true. |
failed | status | Carries error. |
scheduled | status | Held until scheduledAt. Nothing is on any channel yet. Editable. |
draft | status | Saved 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 과 함께 다시 보내면 같은 주소에 다시 씁니다. 네이버에 있는 사진과 서식이 그대로 남습니다. 업리카로 낸 네이버 글도 올린 사진 파일이 정리된 뒤(나간 지 하루쯤)에는 같은 길입니다. 옵션만 고치면 바로 나가고, 본문을 고치면 지금 원문이 먼저 옵니다.
| 이름 | 타입 | 설명 |
|---|---|---|
content | string | New post text. |
accountIds | string[] | New target accounts. Replaces the current set. |
mediaIds | string[] | 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). |
options | object | Per-channel settings. Replaces the whole object. |
scheduledAt | string | New send time, same rules as on create. null turns the post into a draft. |
draft | boolean | true turns a scheduled post, or a Naver Blog post still waiting for the browser extension, back into a draft. |
POST/v1/posts/{id}/publish
예약·초안 글을 지금 보냅니다. 예약 크론과 같은 함수라 두 번 나가지 않습니다.
| 이름 | 타입 | 설명 |
|---|---|---|
wait | boolean | Hold 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
글 하나와 댓글·지표를 한 번에 받습니다.
| 이름 | 타입 | 설명 |
|---|---|---|
accountId | query | Which 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
앱에서 직접 쓴 글까지, 지금 채널에 있는 것.
쿼리
| 이름 | 타입 | 설명 |
|---|---|---|
accountId | query | Limit to one connected account. Omit to cover every channel. |
limit | query | 1-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 다.
| 이름 | 타입 | 설명 |
|---|---|---|
accountId | query | Required. 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)에서만 찾는다. 그래서 가수나 곡 이름으로는 그 곡이 안 나온다. 정렬 · 날짜 조건과 릴스 수 · 만든 날짜가 없고, 검색어는 띄어쓰기까지 맞아야 하며, 인기 목록의 가요에는 음원 파일이 없다.
| 이름 | 타입 | 설명 |
|---|---|---|
accountId | query | Required. A connected Instagram account. Trending audio differs per account, so use ids from the same account's results. |
type | query | music (default) or original_sound. |
query | query | Optional, 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. |
limit | query | 1-50, defaults to 25. |
cursor | query | nextCursor from the previous page, unchanged. |
POST/v1/accounts/select
연결된 채널 중 어디에 올릴지 고릅니다.
POST/v1/accounts/:id/refresh
채널 메타데이터(네이버 블로그 카테고리 · 핀터레스트 보드 등)를 다시 읽습니다. 브라우저 확장을 최대 1분 기다립니다.
| 이름 | 타입 | 설명 |
|---|---|---|
scope | string | 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 를 먼저 부릅니다.
| 이름 | 타입 | 설명 |
|---|---|---|
boardId | string | Required. A board id from the account's pinterest.boards in GET /v1/accounts. Answers with the account, pinterest.defaultBoardId updated. |
| 이름 | 타입 | 설명 |
|---|---|---|
blog필수 | string | A 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>. |
| 이름 | 타입 | 설명 |
|---|---|---|
keywords | string[] | Required. 1-300 keywords. Spaces are fine; the numbers come back per keyword as you sent it. |
save | boolean | Default 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. |
seedText | string | What the person typed, kept with the saved report as its label. Defaults to the first five keywords. |
cacheOnly | boolean | Default 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. |
budgetMs | number | Time 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. |
| 이름 | 타입 | 설명 |
|---|---|---|
keywords | string[] | 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. |
withDocs | boolean | Default true. false measures search volume only. |
budgetMs | number | Time budget for new measurements, default and maximum 60000. Past it the call stops starting upstream requests and returns partial: true with unmeasured. |
| 이름 | 타입 | 설명 |
|---|---|---|
seeds | string[] | 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. |
cached | number | How 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. |
| 이름 | 타입 | 설명 |
|---|---|---|
limit | number | Default 50, newest first. |
| 이름 | 타입 | 설명 |
|---|---|---|
keyword필수 | string | The keyword, as you would send it to measure. A query parameter, since keywords are usually Korean. |
limit | number | Default 100 days, newest first. |
tz | number | The 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). |
GET/v1/research/youtube/search
검색어로 유튜브를 찾아 상위 영상의 조회수 · 구독자 · 길이 · 게시일(유튜브가 준 그대로)과 조회/구독 비율 · 쇼츠/롱폼(업리카가 계산한 값이고 유튜브 지표가 아니라고 dataNotes 가 밝힙니다), 제목 · 훅을 뽑는 붙여넣을 프롬프트를 사람의 업리카 언어(한국어 · 영어)로 줍니다. 같은 검색은 24시간 캐시라 안 세고, 새 검색은 사람당 하루 횟수(응답의 quota)와 공용 YouTube Data API 단위를 씁니다. 기록에 reportId 로 저장됩니다.
| 이름 | 타입 | 설명 |
|---|---|---|
q필수 | string | The search words, as a viewer would type them. |
order | string | viewCount (default), date or relevance. |
period | string | 7d, 1m, 3m, 6m or 1y. Omit for no limit. |
format | string | all (default), shorts or long. 60 seconds or less counts as a Short. |
max | number | 1-50, default 25. |
topic | string | The 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 입니다.
| 이름 | 타입 | 설명 |
|---|---|---|
limit | number | Default 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필수 | string | Two-letter country code such as KR or US. Required, with no default. Ask the person which country they mean. |
language | string | Language code such as ko or en. Leave it out to use the country's main language. |
max | number | How many related keywords to return, biggest first. 1-200, default 50. |
GET/v1/research/ads/search
메타 광고 라이브러리(페이스북 · 인스타그램 · 스레드 · 메신저)의 공개 광고를 키워드나 광고주로 찾습니다. 사람 본인의 광고 계정이 아닙니다. 한 쪽에 최대 30개이고 광고주, 문구, 시작일, 며칠째 돌아가는지, 노출 플랫폼, 형식, thumbnailUrl(며칠 뒤 만료), libraryUrl 이 들며, 다음 쪽 cursor 와 오늘 쓴 횟수가 같이 옵니다. 메타는 광고비와 노출 수를 유럽에서만 공개해 그 숫자는 없습니다. 결과 광고의 advertiser.pageId 를 advertiserId 로 넘기면 같은 광고주의 광고를 이어 봅니다. 같은 검색은 24시간 캐시라 횟수를 안 쓰고, 업체까지 간 쪽마다 하루 횟수를 하나 씁니다. 베타라 사람이 API 키에 대해 끌 수 있습니다.
| 이름 | 타입 | 설명 |
|---|---|---|
q | string | Keywords, as a viewer would search them, up to 100 characters. Pass q or advertiserId, not both. |
advertiserId | string | A Facebook page id from /v1/research/ads/advertisers. Lists that advertiser's ads instead of searching words. |
country | string | Two-letter code of the country the ads were shown in. Default KR. |
status | string | active (default), inactive or all. |
media | string | all (default), image or video. |
sort | string | impressions (default) or relevance. There is no newest-first sort; narrow with from and to instead. |
from | string | Only ads that started on or after this date, YYYY-MM-DD. |
to | string | Only ads that started on or before this date, YYYY-MM-DD. |
exact | boolean | Default false. true keeps only ads with the exact phrase. |
koreanOnly | boolean | Default 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. |
cursor | string | The cursor from the previous page. |
GET/v1/research/ads/advertisers
광고주 이름에 맞는 페이스북 페이지를 메타 광고 라이브러리에서 찾아 인증된 페이지 먼저, 그다음 좋아요 순으로 줍니다. pageId, 분류, 좋아요, 인스타그램 핸들이 듭니다. 같은 이름의 페이지가 여럿인 일이 잦으니 사람이 고르게 한 뒤 그 pageId 를 검색의 advertiserId 로 넘깁니다. 하루 횟수를 하나 쓰고, 같은 이름은 24시간 캐시라 횟수를 안 씁니다.
| 이름 | 타입 | 설명 |
|---|---|---|
q필수 | string | A 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 입니다.
| 이름 | 타입 | 설명 |
|---|---|---|
limit | number | Default 50, newest first. |
GET/v1/research/ads/reports/{id}
저장된 광고 검색 하나를 그때의 광고 목록과 함께 줍니다. 7일이 지나면 resultsExpired 가 true 이고 ads 는 null 이니 다시 검색합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.
GET/v1/research/google-ads/search
구글 광고 투명성 센터(검색 · 유튜브 · 쇼핑 · 지도 · 플레이)의 공개 광고를 웹사이트(domain) 하나나 광고주(advertiserId) 하나로 봅니다. 사람 본인의 구글 애즈 계정이 아닙니다. 한 쪽에 최대 40개를 최근에 나간 순서로 주고, 광고마다 광고주, 형식(텍스트 · 이미지 · 영상), 처음 · 마지막 게재일, runningDays, longRunning, 구글이 그림을 줄 때의 imageUrl, 투명성 센터 원문인 adUrl 이 듭니다. 목록에는 광고 문구가 없어서 사람은 adUrl 로 광고를 봅니다. 구글은 광고비 · 노출 수를 공개하지 않습니다. 웹사이트 결과에는 입점사 · 제휴 브랜드 · 대행사가 각자 이름으로 섞이고 advertisersOnPage 가 그 수를 셉니다. 같은 조회는 24시간 캐시라 횟수를 안 쓰고, 그 밖의 쪽마다 하루 광고 분석 횟수를 하나 씁니다 (메타 광고 분석과 한 칸).
| 이름 | 타입 | 설명 |
|---|---|---|
domain | string | A 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. |
advertiserId | string | A Google advertiser id (AR followed by digits) from /v1/research/google-ads/advertisers or from an ad's advertiser.id. |
region | string | Two-letter code of the country the ads were shown in. Default KR. |
platform | string | all (default), search, youtube, shopping, maps or play. |
format | string | all (default), text, image or video. |
from | string | Only ads shown at any time on or after this date, YYYY-MM-DD. |
to | string | Only ads shown at any time on or before this date, YYYY-MM-DD. |
cursor | string | The cursor from the previous page. |
GET/v1/research/google-ads/advertisers
브랜드나 회사 이름에 맞는 광고주를 구글 광고 투명성 센터에서 찾아 광고 수 추정(adsEstimate)이 큰 순서로 주고, 맞는 웹사이트는 domains 로 줍니다. 구글은 등록한 회사 · 계정마다 광고주를 따로 두어 한 브랜드에 여럿인 일이 잦으니 사람이 고르게 한 뒤 그 advertiserId 를 검색에 넘깁니다. 브랜드 이름이 회사 이름과 다르면 0곳일 수 있으니 법인 이름이나 웹사이트로 찾습니다. 하루 광고 분석 횟수를 하나 쓰고, 같은 이름은 24시간 캐시라 횟수를 안 씁니다.
| 이름 | 타입 | 설명 |
|---|---|---|
q필수 | string | A brand or company name, up to 100 characters. |
region | string | Two-letter country code to search advertisers in. Default KR. |
GET/v1/research/google-ads/reports
저장된 구글 광고 조회 기록을 최신순으로 줍니다. 언제, 웹사이트인지 광고주인지, 나라, 광고 몇 개, 캐시였는지. 메타 광고 검색은 이 목록에 없습니다. 광고 본문은 7일, 기록 줄은 30일 보관합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.
| 이름 | 타입 | 설명 |
|---|---|---|
limit | number | Default 50, newest first. |
GET/v1/research/google-ads/reports/{id}
저장된 구글 광고 조회 하나를 그때의 광고 목록과 함께 줍니다. 7일이 지나면 resultsExpired 가 true 이고 ads 는 null 이니 다시 조회합니다. 기록은 사람 단위라 그 사람의 워크스페이스 전부를 덮지 않는 API 키는 403 forbidden_scope 입니다.
| 이름 | 타입 | 설명 |
|---|---|---|
keywords필수 | string[] | 1-10 keywords, as a reader would search them. |
blog | string | A 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). |
fresh | boolean | Default 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. |
blogTab | boolean | Default 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. |
waitMs | number | Hold 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. |
| 이름 | 타입 | 설명 |
|---|---|---|
limit | number | Default 20, at most 50, newest first. |
| 이름 | 타입 | 설명 |
|---|---|---|
blog필수 | string | A Naver blog id or any link to the blog. |
limit | number | How many recent posts, 1-30, default 20. |
| 이름 | 타입 | 설명 |
|---|---|---|
blog필수 | string | A Naver blog id or any link to the blog. |
tz | number | The 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). |
| 이름 | 타입 | 설명 |
|---|---|---|
mainKeyword필수 | string | 1-100 characters. Used from the next check on; the post's old verdict is cleared. |
title | string | The post title, used only when the post is not tracked yet (up to 300 characters). |
| 이름 | 타입 | 설명 |
|---|---|---|
keyword필수 | string | The keyword, up to 100 characters. A query parameter, since keywords are usually Korean. |
blog | string | Mark that blog's posts and add a verdict to each check. |
limit | number | Default 30, at most 100, newest first. |
| 이름 | 타입 | 설명 |
|---|---|---|
content | string | Required. The Markdown body, up to 60,000 characters. |
title | string | The post title. |
main | string | The main keyword. Without it the keyword checks cannot pass. |
subs | string[] | Sub keywords, one per section title. |
tags | string[] | The tags you will send in options.naver_blog.tags. |
fixedTags | string[] | Tags that need not appear in the body (brand tags). |
products | string[] | Product and brand names that must stay out of the first three paragraphs. |
mediaIds | string[] | The media ids attached to the post, to check that each is placed. |
| 이름 | 타입 | 설명 |
|---|---|---|
content필수 | string | The markdown body to lay out. |
mediaIds | string[] | Attached media, in order. Images the body does not reference are placed by the form. |
form | string | One 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. |
| 이름 | 타입 | 설명 |
|---|---|---|
logNo필수 | string | The draft's id from GET /v1/naver/drafts. |
accountId | string | Required only when the workspace has more than one Naver Blog account. |
title / categoryId / category / tags / openType | string | Override the draft's own values. Left out, the draft goes out as it is. |
wait | boolean | Hold 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. |
| 이름 | 타입 | 설명 |
|---|---|---|
topic | string | One section instead of the whole guide. The 400 lists the ids. |
| 이름 | 타입 | 설명 |
|---|---|---|
url | string | Required. 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. |
| 이름 | 타입 | 설명 |
|---|---|---|
url | string | Required. 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 는 무슨 뜻인가요?
글을 받았고 채널은 아직 대답하지 않았다는 뜻입니다. 무엇이 올라갔는지는 대상별 상태를 봐야 알고, 맨 위 응답은 일이 시작됐다는 것만 말합니다.
올라간 글을 지울 수 있나요?
됩니다. 채널에서 지우고 우리 기록은 삭제로 표시합니다. 그래서 그 글이 있었다는 것과 언제 나갔는지는 기록에 남습니다.