VIVI

Developers

Agent API

개요

Agent API는 VIVI의 기능을 사람 로그인 없이 호출하는 방법입니다. Claude 같은 에이전트의 예약 작업, 사내 자동화, 다른 플랫폼의 커넥터가 대상입니다.

  • 기능 하나가 툴 하나입니다. 같은 툴을 REST와 MCP 양쪽에서 같은 이름과 같은 입력으로 호출합니다.
  • 툴은 화면과 같은 기능을 실행합니다. 같은 입력이면 화면에서 실행한 결과와 같고, 쿼터·크레딧·계약 조건도 화면과 같이 적용됩니다.
  • 최신 툴 목록과 입력 스키마는 언제나 https://app.bubbleshare.io/api/v1/tools와 https://app.bubbleshare.io/api/v1/openapi.json에서 확인할 수 있습니다.

인증과 토큰

에이전트 토큰(vat_…)을 Authorization: Bearer 헤더에 넣어 호출합니다. 토큰은 VIVI 담당자가 발급합니다. 발급할 때 정하는 것은 다음과 같습니다.

항목설명
Organization토큰이 속한 조직 하나
Brand쓸 수 있는 브랜드. 지정하지 않으면 조직의 모든 브랜드
Scoperead(조회), localize:write(현지화 실행) 등 쓸 수 있는 동작
자동 승인Action 크레딧 브랜드에서 사람 승인 없이 실행할 수 있는 월 건수와 선택적 크레딧 상한
만료선택. 지나면 즉시 거부됩니다

토큰은 비밀번호처럼 다룹니다

토큰 원문은 발급할 때 한 번만 전달됩니다. 노출되면 VIVI 담당자에게 알려 폐기하세요. 폐기한 토큰은 즉시 거부됩니다. 요청은 토큰당 시간당 600회까지입니다.

VIVI에 로그인한 사람이 MCP로 연결한 경우에는 그 사람의 화면 권한이 그대로 적용됩니다.

엔드포인트

메서드 · 경로설명
GET /api/v1/tools툴 목록(이름·설명·입력 스키마·scope). 토큰을 넣으면 그 토큰이 쓸 수 있는 툴만 보입니다
POST /api/v1/tools/{name}툴 실행. 본문은 그 툴의 입력 JSON 객체, 응답은 { result }
GET /api/v1/openapi.json같은 툴을 OpenAPI 3.1로. 커넥터·n8n·Zapier 등에서 바로 가져올 수 있습니다

툴 목록

툴Scope하는 일
vivi_get_contextread토큰 정보, 쓸 수 있는 브랜드와 프로젝트(시장·현지화 언어), 자동 승인 한도. 가장 먼저 호출합니다
vivi_localize_createlocalize:write페이지를 프로젝트 시장 언어로 현지화 시작. 현지화 id를 돌려줍니다
vivi_localize_listread프로젝트의 현지화 목록과 각각의 상태, 버전, 승인 상태. 예약 실행 에이전트가 전날 작업을 이어받을 때 씁니다
vivi_localize_statusread진행 상태, 실패 사유, 대기 순번, 편집 화면 링크
vivi_localize_artifactsread완료된 현지화의 산출물: items(AS-IS→TO-BE 행), html, proposal(제안서 HTML), xlsx(작업 시트, base64), page(템플릿 페이지)
vivi_list_project_configread프로젝트의 채널, 카테고리, 질문, 경쟁사
vivi_list_promptsread모니터링 질문 목록과 카테고리·출처·일시정지 상태
vivi_query_project_metricsread기간별 AI 노출 지표(언급·인용·경쟁사 등), 채널·카테고리·질문별
vivi_query_monitoring_url_citationsread추적 페이지가 AI 답변에 인용된 횟수와 그 질문
vivi_query_channel_citationsread추적 채널(YouTube·Instagram·네이버 블로그)의 콘텐츠가 인용된 횟수, 많이 인용된 콘텐츠와 그 질문
vivi_query_pr_citationsread등록 보도자료(PR)의 원문과 재작성 기사가 인용된 횟수, 부분 언급은 따로, 매칭 기사와 그 질문
vivi_keyword_researchreadGoogle·Naver 월간 검색량과 연관 키워드(프로젝트 시장 기준). 조직의 월 키워드 조회 허용량을 씁니다
vivi_localize_pageread현지화로 만든 브랜드 템플릿 페이지의 상태, 고를 수 있는 템플릿, 원문 이미지 목록(이미지 글자 현지화 여부 포함)
vivi_localize_page_createlocalize:write완료된 현지화를 검토한 그대로 브랜드 템플릿 페이지로 만듭니다(모델·크레딧 없음). 현지화당 하루 5개까지
vivi_localize_imagesimages:write원문 이미지(도표·차트 등) 안의 글자를 시장 언어로 다시 그립니다. 크레딧 브랜드는 토큰의 자동 승인 한도 안에서 승인됩니다
vivi_prompts_suggestread페이지(현지화 id 또는 본문)에 맞는 모니터링 질문 후보. 저장하지 않고, 이미 프로젝트에 있는 질문인지 알려줍니다
vivi_list_topicsread질문을 어디에 둘지 고르는 목록. 토픽 기반 프로젝트는 카테고리별 토픽(검색 키워드, 월간 검색량, 측정 여부, 질문 수), 카테고리 기반 프로젝트는 카테고리
vivi_prompts_registerprompts:write질문을 프로젝트 모니터링 세트에 추가합니다. 토픽 기반 프로젝트는 질문마다 기존 토픽(topicId)을 지정하고, 맞는 토픽이 없을 때만 새 토픽(newTopic — 같은 키워드의 토픽이 있으면 그 토픽을 씀)과 필요하면 새 카테고리를 만듭니다. 추가만 하고 기존 질문은 바꾸거나 지우지 않습니다. 플랜의 응답 크레딧이 모자라면 전체를 거절합니다
vivi_urls_trackurls:write게시한 페이지 URL을 추적 페이지로 등록합니다. 다음 크롤부터 AI 답변 인용을 셉니다
vivi_request_approvallocalize:write수정본 버전이나 자동 승인 한도를 넘은 실행의 승인 요청을 이메일로 보냅니다. 브랜드 편집 권한이 있는 조직 구성원에게만 발송됩니다
vivi_localize_optimizelocalize:write현지화한 페이지를 Page Optimizer로 보냅니다. 질문(문장 또는 id, 최대 5개)에 맞춘 개선 계획을 만들고, 개선 페이지는 담당자가 Optimizer 편집기에서 작성합니다
vivi_localize_questionsread현지화 페이지와 가까운 프로젝트의 기존 질문과 유사도, 최근 28일 AI 응답 수. 개선 계획에 넣을 질문을 고를 때 씁니다
vivi_localize_revision_createlocalize:write현지화 행을 고쳐 다음 버전으로 남깁니다. baseVersion이 최신이 아니면 VERSION_CONFLICT로 거절합니다. 승인은 사람이 VIVI 화면에서 합니다

프로젝트 id(prj_…)는 vivi_get_context가 돌려주는 값을 씁니다. 토큰 범위 밖의 프로젝트는 존재 여부와 관계없이 404로 응답합니다.

쓰기와 멱등 키

무언가를 실행하거나 바꾸는 툴(쓰기)은 멱등 키가 필요합니다. Idempotency-Key 헤더나 본문의 idempotencyKey로 보냅니다.

  • 같은 키와 같은 입력으로 다시 보내면 처음 응답을 그대로 돌려줍니다. 두 번 실행되지 않습니다.
  • 같은 키로 다른 입력을 보내면 409(IDEMPOTENCY_CONFLICT)로 거부합니다.
  • 실패한 요청은 기록하지 않으므로 같은 키로 다시 시도할 수 있습니다.
  • 처음 응답이 가리키던 현지화나 페이지가 그 뒤 삭제됐으면 그 키는 풀려서, 같은 키로 보낸 요청을 새로 실행합니다.

키는 작업마다 고유하게 만듭니다. 예: job_id + locale + artifact_version + operation. 모든 쓰기는 VIVI 감사 로그에 남습니다.

크레딧과 자동 승인

Action 크레딧을 쓰는 브랜드에서 크레딧이 드는 툴(예: 현지화)은 견적을 낸 뒤 토큰의 자동 승인 범위 안이면 바로 실행합니다.

  • 범위: 이번 달 자동 승인 건수 안, 그리고 정한 경우 건당·월 크레딧 상한 안
  • 범위를 넘으면 실행하지 않고 status: "awaiting_approval"와 승인 링크(approvalUrl)를 돌려줍니다. 크레딧은 차감되지 않습니다. VIVI 화면에서 사람이 승인하면 실행됩니다.
  • 월 쿼터를 쓰는 브랜드는 화면과 같은 쿼터를 씁니다. 다 쓰면 429 (QUOTA_EXCEEDED)입니다.

오류

오류 응답은 { "error": { "code", "message", "detail" } }형식입니다.

HTTPcode뜻
400INVALID_ARGUMENT입력이 툴의 스키마와 맞지 않음(detail.errors)
401UNAUTHENTICATED토큰 없음·틀림·폐기·만료
403FORBIDDEN토큰에 필요한 scope가 없음
404NOT_FOUND · UNKNOWN_TOOL없거나 범위 밖의 프로젝트·대상, 없는 툴
409IDEMPOTENCY_CONFLICT · IN_PROGRESS · NOT_READY멱등 키 충돌, 같은 키 실행 중, 아직 완료되지 않음
429RATE_LIMITED · QUOTA_EXCEEDED시간당 요청 한도, 월 쿼터 초과
402 · 503CREDITS_UNAVAILABLE · QUOTE_UNAVAILABLE크레딧 부족, 견적 불가(잠시 후 재시도)

예시: 페이지 현지화

1. 쓸 수 있는 프로젝트를 확인합니다.

curl -X POST https://app.bubbleshare.io/api/v1/tools/vivi_get_context \
  -H "Authorization: Bearer $VIVI_TOKEN" -H "Content-Type: application/json" -d '{}'

2. 현지화를 시작합니다. 응답의 localizationId를 기억합니다.

curl -X POST https://app.bubbleshare.io/api/v1/tools/vivi_localize_create \
  -H "Authorization: Bearer $VIVI_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-0001-ko-v1-create" \
  -d '{"projectId":"prj_…","sourceUrl":"https://example.com/article"}'

→ {"result":{"status":"queued","localizationId":48,"editorUrl":"…"}}

3. 상태가 completed가 될 때까지 10~30초 간격으로 확인합니다. 보통 2~5분 걸립니다.

curl -X POST https://app.bubbleshare.io/api/v1/tools/vivi_localize_status \
  -H "Authorization: Bearer $VIVI_TOKEN" -H "Content-Type: application/json" \
  -d '{"projectId":"prj_…","localizationId":48}'

실패하면 failureReason을 봅니다. blocked(사이트가 읽기를 거부)는 나중에 다시 시도하고, not_found·empty는 원문을 사람이 확인합니다. not_needed는 이미 시장 언어로 쓰인 페이지라 현지화가 필요 없다는 뜻입니다.

4. 산출물을 받습니다(format: items · html · proposal · xlsx · page).

curl -X POST https://app.bubbleshare.io/api/v1/tools/vivi_localize_artifacts \
  -H "Authorization: Bearer $VIVI_TOKEN" -H "Content-Type: application/json" \
  -d '{"projectId":"prj_…","localizationId":48,"format":"items"}'

5. 브랜드 템플릿 페이지가 필요하면 vivi_localize_page_create로 만들고, vivi_localize_page의 상태가 ready가 되면vivi_localize_artifacts의 page로 HTML을 받습니다. 원문 이미지 안의 글자는 vivi_localize_images로 현지화합니다.

6. 페이지를 게시한 뒤에는 vivi_prompts_suggest로 질문 후보를 받고, vivi_list_topics에서 각 질문에 맞는 토픽을 골라 고른 것만 vivi_prompts_register로 추가하고, 게시 URL을 vivi_urls_track으로 등록합니다. 다음 크롤부터 인용 성과가 집계됩니다.

curl -X POST https://app.bubbleshare.io/api/v1/tools/vivi_urls_track   -H "Authorization: Bearer $VIVI_TOKEN" -H "Content-Type: application/json"   -H "Idempotency-Key: job-0001-ko-v1-track"   -d '{"projectId":"prj_…","urls":["https://example.co.kr/ko/article"],"publishedDate":"2026-10-20"}'

수정본과 승인

에이전트가 고친 현지화는 번호가 붙은 버전으로 남습니다. vivi_localize_status의 versions.currentVersion을 baseVersion으로 넣어 vivi_localize_revision_create를 호출합니다. 그 사이 누군가 화면에서 고쳤다면 VERSION_CONFLICT와 현재 버전이 돌아오니, 다시 읽고 고칩니다.

승인은 사람만 합니다. vivi_request_approval로 담당자에게 승인 요청 메일을 보내면, 담당자가 메일의 링크로 VIVI에 로그인해 승인합니다. 받는 사람은 이 브랜드의 편집 권한이 있는 조직 구성원이어야 합니다. 승인 뒤에는 vivi_localize_artifacts가 기본으로 승인된 버전을 돌려줍니다. 승인 후 새 버전을 만들면 승인은 이전 버전에 그대로 남고(approvalState = stale), 새 버전은 다시 승인받아야 합니다.

웹훅

토큰에 웹훅 URL을 등록하면(VIVI 운영자에게 요청), 그 토큰이 시작하거나 고친 현지화의 상태가 바뀔 때 VIVI가 POST합니다. 이벤트는 localization.completed·failed·not_needed·approved·approval_released입니다. URL은 https와 고정 도메인만 받습니다.

POST https://your-endpoint.example.com/vivi
X-Vivi-Event-Id: <event id>
X-Vivi-Signature: t=1760400000,v1=<hex HMAC-SHA256(secret, "t.body")>

{"id":"…","type":"localization.completed","createdAt":"…",
 "data":{"projectId":"prj_…","localizationId":48,"status":"completed",
         "failureReason":null,"latestVersion":null,"approvedVersion":null}}

서명을 검증하고, 같은 X-Vivi-Event-Id는 한 번만 처리합니다. 2xx가 아니면 간격을 늘려 6번까지 다시 보냅니다. 웹훅이 없어도 vivi_localize_status로 같은 상태를 읽을 수 있습니다.

MCP로 연결

Claude 같은 MCP 클라이언트에서는 VIVI MCP 서버(https://mcp.bubbleshare.io/api/mcp)를 커넥터로 추가하고, 헤더에 Authorization: Bearer vat_…를 넣습니다. 위 표의 툴이 같은 이름으로 나타납니다.

claude mcp add --transport http vivi https://mcp.bubbleshare.io/api/mcp \
  --header "Authorization: Bearer $VIVI_TOKEN"

VIVI 계정으로 로그인해 연결한 MCP 커넥터(OAuth)도 같은 툴을 쓸 수 있습니다. 이때는 그 계정의 화면 권한이 적용되고, 크레딧이 드는 실행은 VIVI 화면에서 승인합니다.

도움이 되었나요?