Shoalcast API

인증

워크스페이스 > API 키에서 키를 만들고 모든 요청에 Authorization: Bearer sk_shoal_… 헤더로 보내세요. 키는 만들 때 한 번만 보여 주며 서버에는 해시만 저장됩니다. 키는 서버 쪽 환경 변수에 두고, 브라우저 코드나 앱 번들에 넣지 마세요.

빠른 시작

시뮬레이션은 수십 초에서 몇 분이 걸립니다. 생성 후 status가 completed 또는 failed가 될 때까지 몇 초 간격으로 조회하세요.

export SHOAL_API_KEY=sk_shoal_...

# 1) 생성
curl -s -X POST $HOST/api/v1/simulations \
  -H "Authorization: Bearer $SHOAL_API_KEY" -H "Content-Type: application/json" \
  -d '{"question":"구독료를 20% 올리면 사용자 반응은?","agents":12,"rounds":3}'
# → 202 {"id":"sim_...","status":"queued", ...}

# 2) 완료될 때까지 조회
curl -s $HOST/api/v1/simulations/sim_... -H "Authorization: Bearer $SHOAL_API_KEY"

// Node.js (서버 쪽)
const headers = { Authorization: `Bearer ${process.env.SHOAL_API_KEY}`, "Content-Type": "application/json" };
const sim = await fetch(`${HOST}/api/v1/simulations`, {
  method: "POST", headers,
  body: JSON.stringify({ question: "구독료를 20% 올리면 사용자 반응은?" }),
}).then((r) => r.json());

let result = sim;
while (result.status === "queued" || result.status === "running") {
  await new Promise((r) => setTimeout(r, 4000));
  result = await fetch(`${HOST}/api/v1/simulations/${sim.id}`, { headers }).then((r) => r.json());
}
console.log(result.report?.headline);

엔드포인트

시뮬레이션 생성

응답 객체

{
  "id": "sim_8f2c...", "object": "simulation",
  "status": "running",            // queued | running | completed | failed
  "stage": "simulation",          // graph | agents | simulation | report | completed
  "progress": 0.54,
  "engine": "bridge",
  "graph":   { "title", "summary", "entities": [...], "relations": [...], "anchors": [...], "pressures": [...] },
  "agents":  [{ "id": "a1", "name", "segment", "bio", "traits", "stance": -1..1, "influence": 0..1, "platform" }],
  "timelines": [{ "variant": "기본안", "rounds": [{ "round": 1, "event", "summary",
      "posts": [{ "agent_id", "action", "platform", "content", "reply_to_agent_id", "stance" }],
      "sentiment": { "overall": 0.12, "segments": [{ "name", "value" }] } }] }],
  "report": { "headline", "prediction", "confidence": 0..1, "confidence_rationale",
      "segments": [...], "turning_points": [...], "risks": [...], "opportunities": [...],
      "signals_to_watch": [...], "recommendations": [...], "variant_comparison": [...] },
  "error": null
}

후속 질문 · 에이전트 인터뷰

완료된 시뮬레이션 세계에 질문합니다. agent_id를 넣으면 해당 페르소나가 1인칭으로 답합니다.

curl -s -X POST $HOST/api/v1/simulations/sim_.../ask \
  -H "Authorization: Bearer $SHOAL_API_KEY" -H "Content-Type: application/json" \
  -d '{"question":"어떤 설명을 들었다면 해지하지 않았을까요?","agent_id":"a4"}'

설문 API

AI로 설문을 설계하고, 배포하고, 결과와 보고서를 받습니다. 응답 링크는 {host}/s/{token} 형식이며 응답자는 로그인 없이 답합니다. 문항 유형은 single · multi · scale · nps · text 입니다.

# AI로 설문 초안 만들기 (AI 사용 1회)
curl -s -X POST $HOST/api/v1/surveys   -H "Authorization: Bearer $SHOAL_API_KEY" -H "Content-Type: application/json"   -d '{"ai":{"goal":"학생 요금 인상 시 이탈 의향과 이유","audience":"대학생 이용자"}}'

# 배포 시작 → 응답 링크: $HOST/s/<token>
curl -s -X POST $HOST/api/v1/surveys/srv_.../status   -H "Authorization: Bearer $SHOAL_API_KEY" -H "Content-Type: application/json" -d '{"status":"open"}'

# 패널 발송 요청: 20~30대 서울·경기 여성 300명
curl -s -X POST $HOST/api/v1/surveys/srv_.../panel/campaigns \
  -H "Authorization: Bearer $SHOAL_API_KEY" -H "Content-Type: application/json" \
  -d '{"criteria":{"genders":["여성"],"ages":["20대","30대"],"regions":["서울","경기"]},"quota":300}'

# 패널 응답을 연령대로 나눠 본 결과 (segment=_gender | _age | _region)
curl -s "$HOST/api/v1/surveys/srv_.../results?segment=_age" -H "Authorization: Bearer $SHOAL_API_KEY"

# 연령대 문항으로 나눠 본 결과
curl -s "$HOST/api/v1/surveys/srv_.../results?segment=q1a2b3c" -H "Authorization: Bearer $SHOAL_API_KEY"

오류와 한도

오류는 {"error":{"code","message"}} 형태입니다.

• 400 invalid_request — 본문 형식 오류
• 401 invalid_api_key — 키가 없거나 폐기됨
• 403 plan_limit — 요금제의 에이전트·라운드·비교안 한도 초과
• 404 not_found — 다른 계정의 리소스이거나 없음
• 409 not_ready — 완료 전 후속 질문
• 429 quota_exceeded — 이번 달 한도 소진 (usage 포함)
• 502 engine_error — 모델 호출 실패 (질문 한도는 차감되지 않음)