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 | 쓸 수 있는 브랜드. 지정하지 않으면 조직의 모든 브랜드 |
| Scope | read(조회), localize:write(현지화 실행) 등 쓸 수 있는 동작 |
| 자동 승인 | Action 크레딧 브랜드에서 사람 승인 없이 실행할 수 있는 월 건수와 선택적 크레딧 상한 |
| 만료 | 선택. 지나면 즉시 거부됩니다 |
토큰은 비밀번호처럼 다룹니다
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_context | read | 토큰 정보, 쓸 수 있는 브랜드와 프로젝트(시장·현지화 언어), 자동 승인 한도. 가장 먼저 호출합니다 |
vivi_localize_create | localize:write | 페이지를 프로젝트 시장 언어로 현지화 시작. 현지화 id를 돌려줍니다 |
vivi_localize_list | read | 프로젝트의 현지화 목록과 각각의 상태, 버전, 승인 상태. 예약 실행 에이전트가 전날 작업을 이어받을 때 씁니다 |
vivi_localize_status | read | 진행 상태, 실패 사유, 대기 순번, 편집 화면 링크 |
vivi_localize_artifacts | read | 완료된 현지화의 산출물: items(AS-IS→TO-BE 행), html, proposal(제안서 HTML), xlsx(작업 시트, base64), page(템플릿 페이지) |
vivi_list_project_config | read | 프로젝트의 채널, 카테고리, 질문, 경쟁사 |
vivi_list_prompts | read | 모니터링 질문 목록과 카테고리·출처·일시정지 상태 |
vivi_query_project_metrics | read | 기간별 AI 노출 지표(언급·인용·경쟁사 등), 채널·카테고리·질문별 |
vivi_query_monitoring_url_citations | read | 추적 페이지가 AI 답변에 인용된 횟수와 그 질문 |
vivi_query_channel_citations | read | 추적 채널(YouTube·Instagram·네이버 블로그)의 콘텐츠가 인용된 횟수, 많이 인용된 콘텐츠와 그 질문 |
vivi_query_pr_citations | read | 등록 보도자료(PR)의 원문과 재작성 기사가 인용된 횟수, 부분 언급은 따로, 매칭 기사와 그 질문 |
vivi_keyword_research | read | Google·Naver 월간 검색량과 연관 키워드(프로젝트 시장 기준). 조직의 월 키워드 조회 허용량을 씁니다 |
vivi_localize_page | read | 현지화로 만든 브랜드 템플릿 페이지의 상태, 고를 수 있는 템플릿, 원문 이미지 목록(이미지 글자 현지화 여부 포함) |
vivi_localize_page_create | localize:write | 완료된 현지화를 검토한 그대로 브랜드 템플릿 페이지로 만듭니다(모델·크레딧 없음). 현지화당 하루 5개까지 |
vivi_localize_images | images:write | 원문 이미지(도표·차트 등) 안의 글자를 시장 언어로 다시 그립니다. 크레딧 브랜드는 토큰의 자동 승인 한도 안에서 승인됩니다 |
vivi_prompts_suggest | read | 페이지(현지화 id 또는 본문)에 맞는 모니터링 질문 후보. 저장하지 않고, 이미 프로젝트에 있는 질문인지 알려줍니다 |
vivi_list_topics | read | 질문을 어디에 둘지 고르는 목록. 토픽 기반 프로젝트는 카테고리별 토픽(검색 키워드, 월간 검색량, 측정 여부, 질문 수), 카테고리 기반 프로젝트는 카테고리 |
vivi_prompts_register | prompts:write | 질문을 프로젝트 모니터링 세트에 추가합니다. 토픽 기반 프로젝트는 질문마다 기존 토픽(topicId)을 지정하고, 맞는 토픽이 없을 때만 새 토픽(newTopic — 같은 키워드의 토픽이 있으면 그 토픽을 씀)과 필요하면 새 카테고리를 만듭니다. 추가만 하고 기존 질문은 바꾸거나 지우지 않습니다. 플랜의 응답 크레딧이 모자라면 전체를 거절합니다 |
vivi_urls_track | urls:write | 게시한 페이지 URL을 추적 페이지로 등록합니다. 다음 크롤부터 AI 답변 인용을 셉니다 |
vivi_request_approval | localize:write | 수정본 버전이나 자동 승인 한도를 넘은 실행의 승인 요청을 이메일로 보냅니다. 브랜드 편집 권한이 있는 조직 구성원에게만 발송됩니다 |
vivi_localize_optimize | localize:write | 현지화한 페이지를 Page Optimizer로 보냅니다. 질문(문장 또는 id, 최대 5개)에 맞춘 개선 계획을 만들고, 개선 페이지는 담당자가 Optimizer 편집기에서 작성합니다 |
vivi_localize_questions | read | 현지화 페이지와 가까운 프로젝트의 기존 질문과 유사도, 최근 28일 AI 응답 수. 개선 계획에 넣을 질문을 고를 때 씁니다 |
vivi_localize_revision_create | localize: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" } }형식입니다.
| HTTP | code | 뜻 |
|---|---|---|
| 400 | INVALID_ARGUMENT | 입력이 툴의 스키마와 맞지 않음(detail.errors) |
| 401 | UNAUTHENTICATED | 토큰 없음·틀림·폐기·만료 |
| 403 | FORBIDDEN | 토큰에 필요한 scope가 없음 |
| 404 | NOT_FOUND · UNKNOWN_TOOL | 없거나 범위 밖의 프로젝트·대상, 없는 툴 |
| 409 | IDEMPOTENCY_CONFLICT · IN_PROGRESS · NOT_READY | 멱등 키 충돌, 같은 키 실행 중, 아직 완료되지 않음 |
| 429 | RATE_LIMITED · QUOTA_EXCEEDED | 시간당 요청 한도, 월 쿼터 초과 |
| 402 · 503 | CREDITS_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 화면에서 승인합니다.
도움이 되었나요?