API 문서

개요

API는 HTTPS로 호출합니다. 요청 본문과 응답은 JSON 형식을 사용합니다. API 기본 주소는 다음과 같습니다.

https://{host}/api/v1

{host}는 연동 시 안내하는 API 호스트입니다.

데이터는 워크스페이스별로 조회합니다. 요청 경로의 {workspaceId}에는 대상 워크스페이스의 ID를 지정합니다.

API 시작하기

1. API 키 발급

팀 관리자 또는 워크스페이스 관리자가 콘솔의 설정 > 워크스페이스 > API 키에서 키 이름을 입력하고 발급을 선택합니다(이용가이드 5.2 워크스페이스). 발급된 키는 한 번만 표시되므로 복사해 안전하게 보관합니다.

2. 최근 진단 결과 조회

{workspaceId}를 조회할 워크스페이스의 ID로, {apiKey}를 해당 워크스페이스에서 발급한 API 키로 대체합니다.

curl -i 'https://{host}/api/v1/workspaces/{workspaceId}/diagnostics/latest' \
    -H 'Authorization: Bearer {apiKey}'

저장된 진단 결과가 없으면 404와 오류 코드 no_data를 반환합니다.

인증

Authorization 헤더에 API 키를 Bearer {apiKey} 형식으로 지정합니다. 쿼리 파라미터나 쿠키를 통한 인증은 지원하지 않습니다.

Authorization: Bearer {apiKey}

인증이 필요한 요청에 API 키가 없거나 유효하지 않으면 401과 오류 코드 unauthorized를 반환합니다.

• 적용 범위: API 키는 발급된 워크스페이스에서만 사용할 수 있습니다. 요청 경로의 워크스페이스 ID가 다르면 403과 오류 코드 workspace_mismatch를 반환합니다.
• 권한: 모든 키로 데이터 조회, 질문 관리, 진단·수집 요청이 가능합니다. 키별 권한 설정은 지원하지 않습니다.
• 유효 기간: 만료일은 없습니다. 콘솔에서 삭제한 키는 더 이상 인증에 사용할 수 없습니다.
• 발급 한도: 워크스페이스당 최대 5개입니다.

오류

오류가 발생하면 HTTP 상태 코드와 함께 다음 형식의 JSON 본문을 반환합니다.

{
  "error": {
    "code": "workspace_mismatch",
    "message": "This API key does not belong to the requested workspace.",
    "requestId": "73afb161-0238-418c-bc45-00fc6b32dbd8"
  }
}

코드별 HTTP 상태와 발생 조건은 오류 코드 목록을 참고하세요.

최근 진단 결과 조회

완료된 진단 중 최신 결과의 종합 점수, 등급, 항목별 판정 결과를 조회합니다. 같은 브랜드에 속한 워크스페이스는 진단 결과를 공유합니다.

Path Parameters

Response Structure

Example Request

curl -i 'https://{host}/api/v1/workspaces/{workspaceId}/diagnostics/latest' \
    -H 'Authorization: Bearer {apiKey}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "scanId" : "01a02d34-7e21-72c1-bc5b-95efea519b11",
  "scannedAt" : "2026-08-20T01:00:09.983Z",
  "url" : "https://www.movefit.co.kr/",
  "domain" : "www.movefit.co.kr",
  "score" : 78,
  "grade" : "보통",
  "items" : [ {
    "key" : "robots_txt",
    "label" : "robots.txt",
    "category" : "crawl",
    "result" : "pass",
    "score" : 7,
    "weight" : 7,
    "message" : "1/1 기준 모두 통과"
  }, {
    "key" : "sitemap",
    "label" : "sitemap.xml",
    "category" : "crawl",
    "result" : "fail",
    "score" : 0,
    "weight" : 8,
    "message" : "sitemap을 가져오지 못함 · 크롤러도 읽을 수 없음"
  }, {
    "key" : "geo_ai_crawler_access",
    "label" : "AI crawler 접근 정책",
    "category" : "geo",
    "result" : "pass",
    "score" : 8,
    "weight" : 8,
    "message" : "3/3 기준 모두 통과"
  } ]
}

Errors

AI 답변 노출 조회

지정한 기간의 AI 답변에서 브랜드의 언급 건수, 평균 순위, 상위 3위 노출 건수와 경쟁 브랜드별 지표를 조회합니다.

Path Parameters

Query Parameters

Response Structure

Example Request

curl -i 'https://{host}/api/v1/workspaces/{workspaceId}/geo?period=30d' \
    -H 'Authorization: Bearer {apiKey}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "range" : {
    "from" : "2026-07-22",
    "to" : "2026-08-20",
    "snapshotCount" : 17
  },
  "sampleSize" : 504,
  "mentionRate" : {
    "mentioned" : 271,
    "total" : 504
  },
  "averageRank" : 2.8,
  "top3Count" : 46,
  "competitors" : [ {
    "name" : "요가라인",
    "isPrimary" : true,
    "exposedCount" : 188,
    "totalCount" : 504,
    "averageRank" : 1.9
  }, {
    "name" : "핏하우스",
    "isPrimary" : false,
    "exposedCount" : 124,
    "totalCount" : 504,
    "averageRank" : 2.5
  } ]
}

Errors

검색 답변 노출 조회

지정한 기간의 Google·Naver·YouTube 검색 결과와 Google AI Overview·Naver AI 브리핑에서 브랜드 언급률과 자사 콘텐츠 노출률을 조회합니다.

Path Parameters

Query Parameters

Response Structure

Example Request

curl -i 'https://{host}/api/v1/workspaces/{workspaceId}/aeo?period=30' \
    -H 'Authorization: Bearer {apiKey}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "range" : {
    "from" : "2026-07-27",
    "to" : "2026-08-25"
  },
  "kpi" : {
    "organicBrandMention" : { "count" : 16, "total" : 16, "rate" : 100 },
    "organicExposure" : { "count" : 7, "total" : 16, "rate" : 43.8 },
    "averageGoogleRank" : { "value" : 4.5, "sampleSize" : 4 },
    "aiGeneration" : { "count" : 16, "total" : 16, "rate" : 100 },
    "aiBrandMention" : { "count" : 7, "total" : 16, "rate" : 43.8 },
    "aiOwnedCitation" : { "count" : 1, "total" : 16, "rate" : 6.3 }
  },
  "keywords" : [ {
    "keyword" : "요가매트 추천",
    "isActive" : true
  }, {
    "keyword" : "홈트 매트 두께",
    "isActive" : true
  } ]
}

Errors

종합 리포트 조회

진단 결과와 AI 답변·검색 노출을 종합한 리포트를 조회합니다. 응답은 장(chapters)과 각 장의 내용인 블록(blocks)으로 구성됩니다.

Path Parameters

Query Parameters

Response Structure

Example Request

curl -i 'https://{host}/api/v1/workspaces/{workspaceId}/report?period=30d' \
    -H 'Authorization: Bearer {apiKey}'

Example Response (일부)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "range" : {
    "from" : "2026-07-25",
    "to" : "2026-08-23",
    "snapshotCount" : 19
  },
  "brand" : "무브핏",
  "domain" : "movefit.co.kr",
  "chapters" : [ {
    "key" : "summary",
    "title" : "요약",
    "blocks" : [ {
      "kind" : "paragraphs",
      "items" : [ "최근 30일 동안 AI 답변에서 브랜드가 언급된 비율은 54%입니다." ]
    } ]
  }, {
    "key" : "competitor",
    "title" : "경쟁 브랜드 비교",
    "blocks" : [ {
      "kind" : "heading",
      "text" : "브랜드 언급률"
    }, {
      "kind" : "bars",
      "rows" : [ {
        "name" : "무브핏",
        "value" : 271,
        "max" : 504,
        "label" : "54%",
        "mark" : true
      }, {
        "name" : "요가라인",
        "value" : 188,
        "max" : 504,
        "label" : "37%"
      } ]
    } ]
  } ]
}

블록 종류

kind는 블록 종류를 나타냅니다. 지원하지 않는 kind는 표시에서 제외합니다.

Errors

질문 목록 조회

AI 답변 수집에 사용하는 질문 목록을 조회합니다. 보관된 질문은 포함하고 삭제된 질문은 제외합니다.

Response Structure

Example Request

curl -i 'https://{host}/api/v1/workspaces/{workspaceId}/questions' \
    -H 'Authorization: Bearer {apiKey}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "questions" : [ {
    "id" : "019fcbfb-e57f-702f-bc63-c0827329ac8f",
    "query" : "요가매트 추천",
    "isActive" : true,
    "createdAt" : "2026-08-04T08:55:10.975Z"
  }, {
    "id" : "019fcbfb-f883-7d0b-8af6-219877f23a81",
    "query" : "홈트 매트 두께 어느 정도가 좋아?",
    "isActive" : false,
    "createdAt" : "2026-08-04T08:55:15.843Z"
  } ],
  "activeLimit" : 10
}

질문 추가

AI 답변 수집에 사용할 질문을 추가합니다. 같은 문구의 질문이 있으면 기존 질문을 반환하며, 보관되거나 삭제된 질문은 다시 활성화합니다. 기존 id와 createdAt은 유지됩니다.

Request Structure

Response Structure

Example Request

curl -i -X POST 'https://{host}/api/v1/workspaces/{workspaceId}/questions' \
    -H 'Authorization: Bearer {apiKey}' \
    -H 'Content-Type: application/json' \
    -d '{"query":"요가매트 추천"}'

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : "019fcbfb-e57f-702f-bc63-c0827329ac8f",
  "query" : "요가매트 추천",
  "isActive" : true,
  "createdAt" : "2026-08-04T08:55:10.975Z"
}

기존 질문의 문구 수정은 지원하지 않습니다. 변경하려면 기존 질문을 삭제하고 새 문구로 추가합니다.

Errors

질문 삭제

질문을 목록에서 삭제하고 수집 대상에서 제외합니다. 기존 수집 결과는 삭제하지 않습니다.

Path Parameters

Response Structure

Example Request

curl -i -X DELETE 'https://{host}/api/v1/workspaces/{workspaceId}/questions/{questionId}' \
    -H 'Authorization: Bearer {apiKey}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : "019fcbfb-e57f-702f-bc63-c0827329ac8f",
  "collectionInProgress" : false
}

Errors

진단·수집 요청

사이트 진단, AI 답변 수집, 검색 수집을 요청합니다. 작업은 비동기로 실행하며, 응답에는 접수 결과를 반환합니다.

요청 본문은 없습니다. 세 종류의 작업을 모두 요청합니다.

Response Structure

Example Request

curl -i -X POST 'https://{host}/api/v1/workspaces/{workspaceId}/runs' \
    -H 'Authorization: Bearer {apiKey}'

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "accepted" : [ "diagnostic", "geo" ],
  "skipped" : [ {
    "kind" : "aeo",
    "reason" : "aeo_quota_exceeded"
  } ]
}

하나 이상 접수되면 202, 세 작업 모두 접수되지 않으면 409 conflict를 반환합니다. 409 응답의 error.message에는 작업별 미접수 사유가 포함됩니다.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error" : {
    "code" : "conflict",
    "message" : "Nothing could be started: diagnostic=recently_scanned, geo=no_active_questions, aeo=aeo_unavailable",
    "requestId" : "e023e4ce-6be2-4e29-8e35-1333373336d8"
  }
}

미접수 사유

진단 결과는 최근 진단 결과 조회에서 scanId와 scannedAt으로 구분합니다. 수집 결과는 AI 답변 노출 조회와 검색 답변 노출 조회에서 확인합니다. 작업별 상태 조회 API와 완료 알림 웹훅은 제공하지 않습니다.

Errors

부록: 오류 코드