{
  "openapi": "3.0.3",
  "info": {
    "title": "스와퍼 크리에이터 콘텐츠 API",
    "version": "2026-11-11",
    "description": "스와퍼 크리에이터(제휴 파트너)가 자동차 콘텐츠를 만들 때 쓰는 읽기 위주 API입니다. 입구는 GET /content 하나 — 사이트 공개 콘텐츠 전체를 거르고 본문까지 받습니다(/vehicles·/policy 는 이전 주소로 계속 동작). 모든 응답의 링크에는 요청한 파트너의 추천코드가 들어 있습니다. 월 렌탈료는 금액·조건·기준일이 묶인 형태로만 옵니다. 키는 https://swaper.kr/partner/api 에서 만들거나, AI 에이전트는 POST /register 로 가입하면서 바로 받습니다(안내: https://swaper.kr/creator/ai.md). 한도: 1분 60번, 하루 5,000번."
  },
  "servers": [{ "url": "https://swaper.kr/api/creator/v1" }],
  "security": [{ "bearer": [] }],
  "components": {
    "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "swk_ 로 시작하는 키" } },
    "parameters": {
      "lk": { "name": "lk", "in": "query", "required": false, "description": "내 게시물 링크 코드(영숫자 6자). 넣으면 응답 링크에 붙어 그 링크 실적으로 잡힙니다.", "schema": { "type": "string", "pattern": "^[a-z0-9]{6}$" } },
      "key": { "name": "key", "in": "path", "required": true, "description": "차종 키(예: carnival). GET /vehicles 의 key", "schema": { "type": "string" } }
    },
    "schemas": {
      "Monthly": {
        "type": "object",
        "description": "월 렌탈료 묶음. 콘텐츠에는 text 를 그대로 쓰면 조건·기준일이 함께 들어갑니다.",
        "properties": {
          "amount": { "type": "integer" },
          "currency": { "type": "string", "example": "KRW" },
          "termMonths": { "type": "integer", "example": 60 },
          "annualKm": { "type": "integer", "example": 15000 },
          "deposit": { "type": "string", "example": "없음" },
          "includes": { "type": "array", "items": { "type": "string" } },
          "asOf": { "type": "string", "nullable": true, "description": "재고 확인일 YYYY-MM-DD" },
          "text": { "type": "string" }
        }
      },
      "Links": {
        "type": "object",
        "description": "내 추천코드(+lk)가 들어간 공유 주소. 이 주소만 쓰세요.",
        "properties": { "review": { "type": "string" }, "monthly": { "type": "string" }, "quote": { "type": "string" }, "home": { "type": "string" } }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }
    }
  },
  "paths": {
    "/register": {
      "post": {
        "operationId": "register",
        "summary": "화면 없이 가입하고 추천코드·API 키를 바로 받기 — AI 에이전트용(유형 api). 키는 이 응답에만 담깁니다",
        "description": "파트너 화면 가입과 같은 규칙입니다. 약관(https://swaper.kr/partner/terms)에 agree:true 로 동의해야 하며, 동의 책임은 에이전트를 운영하는 사람에게 있습니다. 수수료를 받으려면 그 사람이 파트너 화면에서 정산 정보(실명·휴대폰 인증)를 넣어야 합니다. 같은 곳에서 짧은 시간에 여러 번 가입할 수 없습니다.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "format": "email", "description": "로그인에 쓸 이메일. 한 주소로 한 계정" },
                  "password": { "type": "string", "minLength": 6, "description": "파트너 화면 로그인 비밀번호" },
                  "name": { "type": "string", "maxLength": 40, "description": "활동명(콘텐츠에 쓰는 이름)" },
                  "channelUrl": { "type": "string", "description": "채널 주소(선택). http(s)로 시작, 없으면 비움" },
                  "agree": { "type": "boolean", "description": "추천 링크 이용 약관 동의. true 만 가입" },
                  "termsVersion": { "type": "string", "description": "동의한 약관 버전(선택, 기본 = 현재 버전). 다르면 400 terms_version" }
                },
                "required": ["email", "password", "name", "agree"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "가입 완료",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "string", "description": "추천코드(영숫자 7자)" },
                    "name": { "type": "string" },
                    "kind": { "type": "string", "example": "api" },
                    "email": { "type": "string" },
                    "apiKey": { "type": "string", "description": "swk_ + 48자. 이 응답에만 담김" },
                    "homeLink": { "type": "string", "example": "https://swaper.kr/?ref=k7m2x9q" },
                    "api": { "type": "string", "example": "https://swaper.kr/api/creator/v1" },
                    "login": { "type": "string", "example": "https://swaper.kr/partner" },
                    "docs": { "type": "string", "example": "https://swaper.kr/creator/ai.md" },
                    "openapi": { "type": "string" },
                    "next": { "type": "array", "items": { "type": "string" }, "description": "가입 뒤 바로 할 요청 순서" },
                    "notice": { "type": "string", "description": "사람이 해야 하는 것(정산 정보·수수료 상담)" }
                  }
                }
              }
            }
          },
          "400": { "description": "입력 오류 — code: bad_json · invalid_email · invalid_password · invalid_name · invalid_url · terms_required · terms_version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "이미 가입된 이메일(email_taken) — 파트너 화면에서 로그인한 뒤 [API] 탭에서 키를 만듭니다", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "잠시 가입 불가(unavailable · confirm_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/content": {
      "get": {
        "operationId": "getContent",
        "summary": "★입구 하나 — 스와퍼 공개 콘텐츠 전체(즉시출고 재고·프로모션·전기차·신용·자주 묻는 질문·가이드·월 렌탈료·비교·장단점·영상 쟁점) + 차종 목록 + 콘텐츠 규칙 + 내 링크",
        "description": "조건 없이 부르면 사이트 전체 페이지 색인(종류·제목·설명·관련 차종·갱신일·내 링크)과 차종 목록(재고 수·월 렌탈료 묶음)이 옵니다. vehicle 로 거르면 그 차종의 장단점·재고 요약(vehicle)이 함께 옵니다. 본문(text)·자주 묻는 질문(faq)은 path 로 한 페이지를 고르거나 text=1 로 거른 결과에 싣습니다(20페이지까지). link 가 null 인 페이지는 링크를 만들 수 없는 주소이니 partner.homeLink 를 쓰세요.",
        "parameters": [
          { "name": "type", "in": "query", "required": false, "description": "콘텐츠 종류(쉼표로 여러 개): prebuy · deals · ev · credit · faq · guide · longterm · compare · review · watch. 응답의 types 참고", "schema": { "type": "string" } },
          { "name": "vehicle", "in": "query", "required": false, "description": "차종 키(예: carnival). 응답의 vehicles[].key", "schema": { "type": "string" } },
          { "name": "q", "in": "query", "required": false, "description": "검색어 — 띄어 쓴 말이 제목·설명에 모두 들어간 페이지", "schema": { "type": "string" } },
          { "name": "path", "in": "query", "required": false, "description": "페이지 하나(예: /guide/rent-under-26 또는 https://swaper.kr/… 전체 주소). 본문·자주 묻는 질문 포함", "schema": { "type": "string" } },
          { "name": "text", "in": "query", "required": false, "description": "1 이면 거른 페이지마다 본문·자주 묻는 질문을 싣습니다(20페이지까지, 넘으면 400 too_many_pages)", "schema": { "type": "string", "enum": ["1"] } },
          { "$ref": "#/components/parameters/lk" }
        ],
        "responses": {
          "200": { "description": "OK — version · generatedAt · query · partner · policy · types · vehicles(조건 없을 때) · vehicle(vehicle 로 거를 때) · count · pages[] · next" },
          "400": { "description": "bad_query · too_many_pages · bad_link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "page_not_found — path 의 페이지가 없음", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/content.md": {
      "get": {
        "operationId": "getContentMarkdown",
        "summary": "/content 와 같은 조건을 마크다운 한 장으로 — AI 도구·편집기에 그대로 붙여 넣는 용도. 끝에 작성 규칙",
        "parameters": [
          { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "vehicle", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1"] } },
          { "$ref": "#/components/parameters/lk" }
        ],
        "responses": { "200": { "description": "OK", "content": { "text/markdown": { "schema": { "type": "string" } } } } }
      }
    },
    "/me": {
      "get": {
        "operationId": "getMe",
        "summary": "내 추천코드·정산 상태·오늘 호출 수",
        "responses": { "200": { "description": "OK" }, "401": { "description": "키 없음·틀림", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }
      }
    },
    "/policy": {
      "get": { "operationId": "getPolicy", "summary": "콘텐츠 규칙 — 금칙어·가격 표기·링크 규칙", "responses": { "200": { "description": "OK" } } }
    },
    "/vehicles": {
      "get": {
        "operationId": "listVehicles",
        "summary": "차종 목록 — 즉시출고 재고 수·월 렌탈료 묶음·내 링크",
        "parameters": [{ "$ref": "#/components/parameters/lk" }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/vehicles/{key}": {
      "get": {
        "operationId": "getVehicle",
        "summary": "차종 자료 — 좋은 점·아쉬운 점·엔진 고르기·이런 분께·재고 요약·출처 영상·내 링크",
        "parameters": [{ "$ref": "#/components/parameters/key" }, { "$ref": "#/components/parameters/lk" }],
        "responses": { "200": { "description": "OK" }, "404": { "description": "없는 차종" } }
      }
    },
    "/vehicles/{key}/content.md": {
      "get": {
        "operationId": "getVehicleMarkdown",
        "summary": "차종 자료 한 장(마크다운) — AI 도구에 그대로 붙여 넣는 용도. 끝에 기준일·작성 규칙",
        "parameters": [{ "$ref": "#/components/parameters/key" }, { "$ref": "#/components/parameters/lk" }],
        "responses": { "200": { "description": "OK", "content": { "text/markdown": { "schema": { "type": "string" } } } } }
      }
    },
    "/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "내 추천 링크로 들어온 견적 신청 건수 — 날짜·유입 경로(utm_source)별. 방문 수·고객 정보는 없음",
        "parameters": [{ "name": "days", "in": "query", "description": "최근 며칠(한국 시간, 오늘 포함). 1~90, 기본 30", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } }],
        "responses": {
          "200": { "description": "code·from·to·total·bySource·daily[{date,leads,bySource}]·rows[{date,source,leads}]. 유입 경로 = 링크의 utm_source(없으면 첫 진입 referrer 도메인, 그래도 없으면 unknown)" },
          "400": { "description": "days 가 1~90 이 아님", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "키 없음·틀림", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/links": {
      "get": { "operationId": "listLinks", "summary": "내 게시물 링크 목록", "responses": { "200": { "description": "OK" } } },
      "post": {
        "operationId": "createLink",
        "summary": "게시물 링크 만들기 — 스와퍼 고객 페이지 주소만",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": { "type": "string", "example": "https://swaper.kr/review/carnival" },
                  "label": { "type": "string", "example": "유튜브 카니발 쇼츠" }
                },
                "required": ["url"]
              }
            }
          }
        },
        "responses": { "201": { "description": "만든 링크(code·url)" }, "400": { "description": "스와퍼 주소가 아님·링크 200개 초과" } }
      }
    }
  }
}
