무료로 시작
DEVELOPER RECORD / 개발자 문서

API 문서

VibeBot API는 OpenAI Chat Completions와 요청·응답 형식이 같습니다. 기존 OpenAI SDK에서 baseURL만 바꾸고 model 자리에 챗봇 ID를 넣으면 그대로 동작합니다.

베이스 URL https://vibebot.store/v1

붙이는 법

쓰는 스택을 고르세요.

사이트가 없어도 된다. 이 주소가 곧 챗봇이다
https://vibebot.store/c/agt_9f2c

카톡·인스타 프로필·메일 서명에 붙이면 끝. 붙일 코드가 없다.

엔드포인트

베이스 URL: https://vibebot.store/v1

POST /v1/chat/completions
curl https://vibebot.store/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer vb_sk_..." \
  -d '{
    "model": "agt_9f2c",
    "messages": [{"role": "user", "content": "환불 되나요?"}],
    "stream": false
  }'
응답 — OpenAI 호환 + vibebot 확장
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "agt_9f2c",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "배송 후 7일 이내면 가능합니다." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 812, "completion_tokens": 24, "total_tokens": 836 },

  "vibebot": {
    "sources": [{ "id": "chk_1", "title": "환불 정책", "url": "..." }],
    "escalate": false
  }
}

vibebot.sources는 답이 어느 자료에서 나왔는지(레퍼런스)입니다. escalate가 true면 근거를 찾지 못했다는 뜻이니 사람에게 넘기세요.

스트리밍

stream: true를 주면 OpenAI 스타일 SSE로 옵니다. 마지막 청크에만 vibebot 필드가 실리고, data: [DONE]으로 끝납니다.

인증

  • 서버에서 호출 — Authorization: Bearer vb_sk_... (설정에서 발급)
  • 브라우저 위젯 — 키 불필요. 챗봇 ID만 있으면 됩니다.

위젯은 키가 없으므로 허용 도메인으로 보호합니다. 대시보드 → 붙일 수 있는 도메인에서 지정하고, 비워두면 어느 사이트에서나 열립니다 — 그 상태로 운영하면 다른 사람이 코드를 복사해 내 한도를 쓸 수 있습니다. https://*.example.com 처럼 서브도메인 전체도 됩니다.

코드 없이 붙이기

  • 링크 공유 — https://vibebot.store/c/:id 를 보내면 그대로 대화창이 열립니다.
  • iframe — https://vibebot.store/embed/:id. 노션·구글 사이트·쇼핑몰 임베드 블록에 넣습니다.
  • 모바일 앱 — 같은 /embed/:id 를 WebView 로 띄우면 됩니다. SDK 가 필요 없어요.

파일 업로드

POST /v1/agents/:id/files
curl -X POST https://vibebot.store/v1/agents/agt_9f2c/files \
  -H "authorization: Bearer $VIBEBOT_KEY" \
  -F "file=@약관.pdf" -F "file=@요금표.csv"

txt · md · csv · tsv · json · html · pdf, 한 개당 최대 2MB(Free) ~ 8MB(유료). 한 번에 여러 개를 보낼 수 있고, 일부만 실패하면 성공한 것은 그대로 들어가고 실패 목록이 failed 로 옵니다.

관리 API

챗봇을 코드로 만들고 자료를 넣을 수 있습니다. CI에서 문서가 바뀔 때마다 자료를 갱신하거나, 고객사마다 챗봇을 자동으로 만들 때 씁니다. 이 엔드포인트들은 API 키가 반드시 필요합니다 — 위젯처럼 키 없이 부를 수 없습니다. 브라우저에 키를 심지 마세요.

관리 엔드포인트 — 전부 API 키 필수
메서드경로하는 일
GET/v1/models내 챗봇 목록 (OpenAI 호환 형식)
GET/v1/agents내 챗봇 목록
POST/v1/agents챗봇 생성
PATCH/v1/agents/:id설정 수정 (이름·인사말·허용 도메인·참조 영역)
DELETE/v1/agents/:id삭제
GET/v1/agents/:id/sources자료 목록
POST/v1/agents/:id/sourcesURL·텍스트 추가
POST/v1/agents/:id/files파일 업로드 (multipart, 여러 개 가능)
DELETE/v1/agents/:id/sources/:sourceId자료 삭제
GET/v1/agents/:id/wiki위키 페이지·진행 상황
POST/v1/agents/:id/wiki위키 생성 (기본은 완료까지 대기)
GET/v1/agents/:id/conversations대화 로그
SDK — 챗봇 만들고 자료 넣기
// 챗봇 만들고 자료 넣기 — 전부 코드로
const vb = new VibeBot({ apiKey: process.env.VIBEBOT_KEY })

const agent = await vb.agents.create({ name: '문서봇' })
await vb.agents.sources.create(agent.id, { url: 'https://mysite.com' })

// 무엇을 못 답했는지 확인
const log = await vb.agents.conversations(agent.id, { limit: 50 })
log.filter((c) => c.escalated).forEach((c) => console.log(c.question))

URL을 넣으면 같은 도메인을 최대 8페이지까지 따라가며 읽습니다. 한 페이지만 원하면 crawl: false를 주세요.

에러

에러 코드와 발생 조건
HTTPcode언제
400missing_model · missing_messages · invalid_message요청 형식이 잘못됨 (model 누락, messages 비어 있음, 잘못된 role 등)
400unsupported_parametertools·response_format 등 지원하지 않는 파라미터. 조용히 무시하지 않습니다
400no_sources자료 없이 위키 생성 요청
401invalid_api_keyAPI 키가 틀림 — 키를 아예 빼면 위젯 방식으로 동작합니다
401origin_not_allowed허용 도메인 목록에 없는 사이트에서 위젯 호출
402quota_exceeded이번 달 메시지 한도 소진 — 업그레이드 필요
404agent_not_found존재하지 않는 챗봇 ID
404unknown_endpoint없는 /v1 경로. 항상 JSON으로 답합니다
429rate_limit_exceeded분당 요청 초과 — Retry-After 및 x-ratelimit-* 헤더 참고
500upstream_error모델 호출 실패

헤드리스 모드

위젯 UI 대신 훅만 쓰고 화면은 직접 만들 수 있습니다.

useVibeBot()
import { useVibeBot } from '@vibe-bot/react'

function MyChat() {
  const { messages, send, isLoading, sources } = useVibeBot({
    agentId: 'agt_9f2c',
  })

  return (
    <div>
      {messages.map((m, i) => <p key={i}>{m.content}</p>)}
      <button onClick={() => send('안녕')}>보내기</button>
    </div>
  )
}
API 문서 — VibeBot