{"openapi":"3.1.0","info":{"title":"봄누리 광고 API(에이전트용)","version":"1.0.0","summary":"쿠팡 파트너스 링크로 육아 정보 사이트 네트워크에 광고 초안을 만들고 검토를 제출한다.","description":"AI 에이전트가 광고를 집행할 수 있게 만든 API 입니다. 같은 작업을 MCP(`/mcp`)로도 쓸 수 있습니다.\n\n- 인증: `Authorization: Bearer pcads_…` (콘솔에서 발급, 광고주 하나에 묶임)\n- 돈: 만들기는 초안이고, 승인되면 결제 연결 전 상태(`awaiting_payment`)에서 멈춥니다. 집행 시작·재개는 사람만 합니다.\n- 한도: 키당 분당 60요청·쓰기 20 — 응답 헤더 `RateLimit-*`, 넘으면 429 + `Retry-After`.\n- 멱등: 쓰기에 `Idempotency-Key` 헤더(24시간).\n- 지표: 봇·AI 활동은 노출·클릭에서 뺍니다.","contact":{"email":"contact@bomnuri.com"}},"servers":[{"url":"https://bomnuri.com/api/ads/v1"}],"externalDocs":{"description":"개발자 안내","url":"https://bomnuri.com/ads/developers/"},"x-mcp":{"url":"https://bomnuri.com/mcp","transport":"streamable-http","protocolVersions":["2026-07-28","2025-11-25","2025-06-18"]},"tags":[{"name":"읽기"},{"name":"쓰기"},{"name":"키 관리"}],"paths":{"/account":{"get":{"operationId":"get_account","summary":"내 광고 계정","description":"이 API 키가 묶인 광고주, 키 권한(스코프), 한도, 광고 집행 순서를 돌려준다. 처음 연결했을 때 먼저 부르세요.\n\n스코프: `ads:read` · MCP 도구 이름: `get_account`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/placements":{"get":{"operationId":"list_placements","summary":"광고 지면 목록","description":"광고가 들어갈 수 있는 지면과 추천 이유·기대 효과·조건. 지면을 고르지 않으면 맞는 지면 전체에 나간다.\n\n스코프: `ads:read` · MCP 도구 이름: `list_placements`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/targeting-options":{"get":{"operationId":"list_targeting_options","summary":"타기팅 값 목록","description":"타기팅에 쓸 수 있는 사이트(slug·주제)와 육아 단계. 사람 정보(나이·성별·관심사·위치)로는 타기팅하지 않는다.\n\n스코프: `ads:read` · MCP 도구 이름: `list_targeting_options`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/estimate":{"post":{"operationId":"estimate_reach","summary":"예상 노출","description":"타기팅 조건의 예상 하루 노출(최근 7일 실제 서빙 수 평균, 봇·AI 제외). 주제·키워드로 좁히면 상한값이다.\n\n스코프: `ads:read` · MCP 도구 이름: `estimate_reach`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"targeting":{"type":"object","description":"문맥 타기팅(사람 정보 없음). 빈 배열·빠진 칸 = 제한 없음, 칸끼리는 AND. 값은 list_targeting_options 에서.","properties":{"sites":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":63},"description":"사이트 slug(예: newborn)"},"categories":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":130},"description":"「사이트:주제」(예: babyfood:stages)"},"keywords":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":30},"description":"글 문맥 키워드"},"stages":{"type":"array","maxItems":5,"items":{"type":"string","enum":["pregnancy","newborn","infant","toddler","preschool"]},"description":"육아 단계"}},"additionalProperties":false}},"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/policy/check":{"post":{"operationId":"check_policy","summary":"광고 정책 사전 검사","description":"문안·링크를 제출 전에 검사한다. issues 의 code·message 로 고친 뒤 다시 검사하세요. 저장하지 않는다.\n\n스코프: `ads:read` · MCP 도구 이름: `check_policy`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"headline":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":400},"productName":{"type":"string","maxLength":200},"productCategory":{"type":"string","enum":["general","baby_food","formula","health_food","medical_device","child_product","cosmetics","quasi_drug","drug"],"description":"정책 분류. formula(분유)·drug 는 받지 않는다. health_food·medical_device·child_product·baby_food·quasi_drug 는 심의필·KC 번호(approvalRefs)가 필요하다"},"landingUrl":{"type":"string","maxLength":500,"description":"쿠팡 파트너스 링크"},"imageUrl":{"type":"string","maxLength":500},"cta":{"type":"string","maxLength":40},"approvalRefs":{"type":"object","description":"심의필·인증 번호 {\"health_food_review\":\"…\",\"kc\":\"…\",\"medical_device_review\":\"…\"}"}},"required":["headline","landingUrl"],"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/copy/suggest":{"post":{"operationId":"suggest_ad_copy","summary":"AI 문안 초안","description":"상품명·키워드(·쿠팡 파트너스 링크)로 광고 제목·설명 초안 최대 3개와 추천 지면을 만든다. 정책 검사를 통과한 초안만 돌려준다. 20~40초 걸릴 수 있고 광고주당 하루 20회.\n\n스코프: `ads:read` · MCP 도구 이름: `suggest_ad_copy`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productName":{"type":"string","minLength":1,"maxLength":80,"description":"상품 이름(쿠팡 상품명 그대로 가능)"},"keywords":{"type":"array","maxItems":8,"items":{"type":"string","minLength":1,"maxLength":20},"description":"문맥 키워드(예: 신생아, 출산준비)"},"landingUrl":{"type":"string","pattern":"^https://(link\\.coupang\\.com/a/[A-Za-z0-9]+|coupa\\.ng/[A-Za-z0-9]+)/?(\\?\\S*)?$","description":"쿠팡 파트너스 링크(있으면)"},"productCategory":{"type":"string","enum":["general","baby_food","formula","health_food","medical_device","child_product","cosmetics","quasi_drug","drug"],"description":"정책 분류. formula(분유)·drug 는 받지 않는다. health_food·medical_device·child_product·baby_food·quasi_drug 는 심의필·KC 번호(approvalRefs)가 필요하다"},"facts":{"type":"string","maxLength":200,"description":"소재·크기·구성 같은 사실 — 문안은 이 사실만 쓴다"}},"required":["productName"],"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/campaigns":{"get":{"operationId":"list_campaigns","summary":"캠페인 목록","description":"이 광고주의 캠페인(보관 제외)과 상태·오늘 노출·클릭.\n\n스코프: `ads:read` · MCP 도구 이름: `list_campaigns`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[],"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}},"post":{"operationId":"create_campaign_draft","summary":"캠페인 초안 만들기","description":"캠페인을 초안(draft)으로 만든다. 돈은 나가지 않는다 — 검토·결제 전에는 노출되지 않는다. 다음은 add_creative_from_coupang_url.\n\n스코프: `ads:write` · MCP 도구 이름: `create_campaign_draft`","tags":["쓰기"],"security":[{"apiKey":["ads:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$","description":"같은 값으로 다시 보내면 처음 결과를 그대로 돌려준다(24시간). 재시도할 때 쓰세요. REST 는 Idempotency-Key 헤더."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"캠페인 이름"},"objective":{"type":"string","enum":["clicks","reach"],"description":"목표(기본 clicks)"},"bidStrategy":{"type":"string","enum":["cpc","cpm"],"description":"입찰 방식(기본: clicks→cpc, reach→cpm)"},"bidAmount":{"type":"integer","minimum":0,"maximum":1000000,"description":"원. cpc=클릭당, cpm=노출 1,000회당"},"budgetType":{"type":"string","enum":["daily","total"]},"budgetAmount":{"type":"integer","minimum":0,"maximum":1000000000,"description":"원"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"KST 날짜"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"KST 날짜(포함)"},"targeting":{"type":"object","description":"문맥 타기팅(사람 정보 없음). 빈 배열·빠진 칸 = 제한 없음, 칸끼리는 AND. 값은 list_targeting_options 에서.","properties":{"sites":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":63},"description":"사이트 slug(예: newborn)"},"categories":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":130},"description":"「사이트:주제」(예: babyfood:stages)"},"keywords":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":30},"description":"글 문맥 키워드"},"stages":{"type":"array","maxItems":5,"items":{"type":"string","enum":["pregnancy","newborn","infant","toddler","preschool"]},"description":"육아 단계"}},"additionalProperties":false},"dryRun":{"type":"boolean","description":"true 면 검사만 하고 저장하지 않는다(정책 검사 결과 포함)."}},"required":["name"],"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},"responses":{"201":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/campaigns/{campaignId}":{"get":{"operationId":"get_campaign_status","summary":"캠페인 상태","description":"캠페인 상태, 소재별 검토 결과(정책 코드·사유), 사람에게 전할 다음 단계 문장(nextStep).\n\n스코프: `ads:read` · MCP 도구 이름: `get_campaign_status`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"캠페인 id(create_campaign_draft 가 돌려준 값)"}}],"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/campaigns/{campaignId}/report":{"get":{"operationId":"get_report","summary":"성과 보고","description":"일별 노출(served)·보임(viewable)·클릭·CTR·예상 비용. 봇·AI 활동은 빼고 센다(filtered 는 따로). 기본 최근 7일, 최대 92일.\n\n스코프: `ads:read` · MCP 도구 이름: `get_report`","tags":["읽기"],"security":[{"apiKey":["ads:read"]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"캠페인 id(create_campaign_draft 가 돌려준 값)"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"KST 날짜 YYYY-MM-DD"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"KST 날짜 YYYY-MM-DD(포함)"}}],"x-mcp-annotations":{"readOnlyHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/Error429"}}}},"/campaigns/{campaignId}/creatives":{"post":{"operationId":"add_creative_from_coupang_url","summary":"쿠팡 링크로 소재 추가","description":"쿠팡 파트너스 링크(link.coupang.com/a/… 또는 coupa.ng/…)로 소재를 추가한다. headline 을 비우면 AI 문안 도우미가 채운다. 정책에 걸리면(422) 저장하지 않고 issues 를 돌려준다.\n\n스코프: `ads:write` · MCP 도구 이름: `add_creative_from_coupang_url`","tags":["쓰기"],"security":[{"apiKey":["ads:write"]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"캠페인 id(create_campaign_draft 가 돌려준 값)"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$","description":"같은 값으로 다시 보내면 처음 결과를 그대로 돌려준다(24시간). 재시도할 때 쓰세요. REST 는 Idempotency-Key 헤더."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"headline":{"type":"string","minLength":1,"maxLength":30,"description":"제목 30자 이하"},"body":{"type":"string","maxLength":60,"description":"설명 60자 이하"},"productName":{"type":"string","maxLength":40,"description":"상품 이름(카드의 굵은 줄) 40자 이하","minLength":1},"productCategory":{"type":"string","enum":["general","baby_food","formula","health_food","medical_device","child_product","cosmetics","quasi_drug","drug"],"description":"정책 분류. formula(분유)·drug 는 받지 않는다. health_food·medical_device·child_product·baby_food·quasi_drug 는 심의필·KC 번호(approvalRefs)가 필요하다"},"imageUrl":{"type":"string","maxLength":500,"pattern":"^https://[a-z0-9.-]+\\.coupangcdn\\.com/","description":"쿠팡 이미지 주소(*.coupangcdn.com)만. 없으면 글자 카드"},"cta":{"type":"string","maxLength":10,"description":"버튼 글자(기본 「쿠팡에서 보기」)"},"approvalRefs":{"type":"object","description":"심의필·인증 번호 {\"health_food_review\":\"…\",\"kc\":\"…\",\"medical_device_review\":\"…\"}"},"landingUrl":{"type":"string","pattern":"^https://(link\\.coupang\\.com/a/[A-Za-z0-9]+|coupa\\.ng/[A-Za-z0-9]+)/?(\\?\\S*)?$","description":"쿠팡 파트너스 링크만"},"keywords":{"type":"array","maxItems":8,"items":{"type":"string","maxLength":20},"description":"headline 을 비웠을 때 문안 도우미에 줄 키워드"},"format":{"type":"string","enum":["product_card","text"]},"origin":{"type":"string","enum":["human","ai"],"description":"문안을 누가 썼나. MCP 기본값 ai, REST 기본값 human(투명성 기록 — 화면에는 안 나감)"},"generator":{"type":"string","maxLength":80,"description":"AI 가 썼다면 「하네스:모델」"},"dryRun":{"type":"boolean","description":"true 면 검사만 하고 저장하지 않는다(정책 검사 결과 포함)."}},"required":["landingUrl","productName"],"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"responses":{"201":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/creatives/{creativeId}":{"patch":{"operationId":"update_creative","summary":"소재 고치기","description":"거절됐거나 고칠 소재의 문안·링크를 바꾼다. 내용이 바뀌면 그 소재만 다시 검토한다. status 로 소재를 켜고 끈다(active|paused).\n\n스코프: `ads:write` · MCP 도구 이름: `update_creative`","tags":["쓰기"],"security":[{"apiKey":["ads:write"]}],"parameters":[{"name":"creativeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"소재 id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$","description":"같은 값으로 다시 보내면 처음 결과를 그대로 돌려준다(24시간). 재시도할 때 쓰세요. REST 는 Idempotency-Key 헤더."}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"landingUrl":{"type":"string","pattern":"^https://(link\\.coupang\\.com/a/[A-Za-z0-9]+|coupa\\.ng/[A-Za-z0-9]+)/?(\\?\\S*)?$"},"headline":{"type":"string","minLength":1,"maxLength":30,"description":"제목 30자 이하"},"body":{"type":"string","maxLength":60,"description":"설명 60자 이하"},"productName":{"type":"string","maxLength":40,"description":"상품 이름(카드의 굵은 줄) 40자 이하"},"productCategory":{"type":"string","enum":["general","baby_food","formula","health_food","medical_device","child_product","cosmetics","quasi_drug","drug"],"description":"정책 분류. formula(분유)·drug 는 받지 않는다. health_food·medical_device·child_product·baby_food·quasi_drug 는 심의필·KC 번호(approvalRefs)가 필요하다"},"imageUrl":{"type":"string","maxLength":500,"pattern":"^https://[a-z0-9.-]+\\.coupangcdn\\.com/","description":"쿠팡 이미지 주소(*.coupangcdn.com)만. 없으면 글자 카드"},"cta":{"type":"string","maxLength":10,"description":"버튼 글자(기본 「쿠팡에서 보기」)"},"approvalRefs":{"type":"object","description":"심의필·인증 번호 {\"health_food_review\":\"…\",\"kc\":\"…\",\"medical_device_review\":\"…\"}"},"status":{"type":"string","enum":["active","paused"]},"origin":{"type":"string","enum":["human","ai"],"description":"문안을 누가 썼나. MCP 기본값 ai, REST 기본값 human(투명성 기록 — 화면에는 안 나감)"},"generator":{"type":"string","maxLength":80,"description":"AI 가 썼다면 「하네스:모델」"}},"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/campaigns/{campaignId}/submit":{"post":{"operationId":"submit_for_review","summary":"검토 제출","description":"캠페인을 검토에 제출한다. 자동 정책 검사 뒤 운영팀이 사람 검토를 한다(자동 승인 없음). 승인되면 awaiting_payment(결제 연결 전)에서 멈춘다.\n\n스코프: `ads:write` · MCP 도구 이름: `submit_for_review`","tags":["쓰기"],"security":[{"apiKey":["ads:write"]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"캠페인 id(create_campaign_draft 가 돌려준 값)"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$","description":"같은 값으로 다시 보내면 처음 결과를 그대로 돌려준다(24시간). 재시도할 때 쓰세요. REST 는 Idempotency-Key 헤더."}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/campaigns/{campaignId}/pause":{"post":{"operationId":"pause_campaign","summary":"캠페인 멈추기","description":"집행 중(active)인 캠페인을 멈춘다. 다시 켜는 것은 사람이 콘솔에서 한다.\n\n스코프: `ads:write` · MCP 도구 이름: `pause_campaign`","tags":["쓰기"],"security":[{"apiKey":["ads:write"]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f-]{36}$","description":"캠페인 id(create_campaign_draft 가 돌려준 값)"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$","description":"같은 값으로 다시 보내면 처음 결과를 그대로 돌려준다(24시간). 재시도할 때 쓰세요. REST 는 Idempotency-Key 헤더."}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/keys":{"get":{"operationId":"list_api_keys","summary":"API 키 목록(사람 전용)","description":"로그인 세션 쿠키로만. 광고주 구성원만 볼 수 있다.","tags":["키 관리"],"security":[{"session":[]}],"parameters":[{"name":"advertiserId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"목록","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"advertiserId":{"type":"string"},"name":{"type":"string"},"displayPrefix":{"type":"string","examples":["pcads_Ab12Cd34"]},"scopes":{"type":"array","items":{"type":"string","enum":["ads:read","ads:write"]}},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"lastUsedAt":{"type":"string"},"revokedAt":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Error401"},"404":{"$ref":"#/components/responses/Error404"}}},"post":{"operationId":"create_api_key","summary":"API 키 만들기(사람 전용)","description":"원문(secret)은 이 응답에서 한 번만 보인다. viewer 는 ads:read 키만 만들 수 있다. 같은 주소 Origin + JSON.","tags":["키 관리"],"security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"advertiserId":{"type":"string"},"name":{"type":"string","maxLength":40},"scopes":{"type":"array","items":{"type":"string","enum":["ads:read","ads:write"]}},"expiresInDays":{"type":"integer","minimum":1,"maximum":365}},"required":["advertiserId","name"]}}}},"responses":{"201":{"description":"만듦","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string"},"advertiserId":{"type":"string"},"name":{"type":"string"},"displayPrefix":{"type":"string","examples":["pcads_Ab12Cd34"]},"scopes":{"type":"array","items":{"type":"string","enum":["ads:read","ads:write"]}},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"lastUsedAt":{"type":"string"},"revokedAt":{"type":"string"}}},"secret":{"type":"string","examples":["pcads_…"]}}}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"}}}},"/keys/{keyId}/revoke":{"post":{"operationId":"revoke_api_key","summary":"API 키 폐기(사람 전용)","tags":["키 관리"],"security":[{"session":[]}],"parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"폐기됨","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string"},"advertiserId":{"type":"string"},"name":{"type":"string"},"displayPrefix":{"type":"string","examples":["pcads_Ab12Cd34"]},"scopes":{"type":"array","items":{"type":"string","enum":["ads:read","ads:write"]}},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"lastUsedAt":{"type":"string"},"revokedAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"pcads_<43자>","description":"광고주 API 키. 스코프 ads:read · ads:write"},"session":{"type":"apiKey","in":"cookie","name":"pc_session","description":"사람 로그인 세션(콘솔) — 키 관리 전용"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","enum":["bad_request","unauthenticated","insufficient_scope","advertiser_suspended","forbidden","not_found","conflict","too_large","policy","idempotency_key_reused","rate_limited","not_configured","internal"]},"detail":{"type":"string"},"message":{"type":"string","description":"사람에게 그대로 보여도 되는 한국어 한 문장"},"issues":{"type":"array","items":{"type":"object"},"description":"정책 위반(422 policy)"}},"required":["error","message"]}},"responses":{"Error400":{"description":"bad_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error401":{"description":"unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error403":{"description":"insufficient_scope · advertiser_suspended · forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"policy · idempotency_key_reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}