Try API Reference

カスタマージャーニー可視化システム「Try」の REST API。

基本情報

Base URL: https://try.stagbeetle.group/api/v1
Format: JSON (UTF-8必須、Shift_JISは400で拒否)
レスポンス形式: {"data": ...}（204は空）
エラー形式: {"error": "message"}
認証: なし（IPアロー方式、現在は全許可）
姉妹システム: Fudo (box.stagbeetle.group) / Love (love.stagbeetle.group)

概念

Journey (1プロジェクト = 1カスタマージャーニー)
  └─ ExperienceNode (体験ノード) ──┬── ExperienceEdge (ノード間接続)
                                   └── NodeImage (ノードに紐づく画像)

各 Journey が独立した体験マップを持ち、ノードとエッジ、画像を管理。

Journeys

Method	Path	Description	Body
GET	`/journeys`	ジャーニー一覧	—
POST	`/journeys`	ジャーニー作成	`{slug, name, description?, default_view?, phases?}`
GET	`/journeys/{slug}`	ジャーニー取得	—
PUT	`/journeys/{slug}`	ジャーニー更新	`{name, description, default_view, phases}`
DELETE	`/journeys/{slug}`	ジャーニー削除（カスケード）	—

Journey オブジェクト

{
  "id": 1,
  "slug": "sample",
  "name": "サンプルジャーニー",
  "description": "ECサイト購入体験",
  "default_view": "canvas",
  "phases": "[\"認知\",\"興味\",\"検討\",\"購入\",\"使用\",\"リピート\"]",
  "sort_order": 0,
  "created_at": "2026-04-09 02:57:40",
  "updated_at": "2026-04-09 02:57:40"
}

default_view: "canvas" または "timeline"
phases: JSON配列文字列（パースして使用）

Experience Nodes (体験ノード)

Method	Path	Description	Body
GET	`/journeys/{slug}/nodes`	ノード一覧	—
POST	`/journeys/{slug}/nodes`	ノード作成	ExperienceNode フィールド (`title` 必須)
PUT	`/journeys/{slug}/nodes/{nodeId}`	ノード更新	全フィールド
PATCH	`/journeys/{slug}/nodes/{nodeId}/position`	座標のみ更新（軽量、ドラッグ用）	`{x, y}`
DELETE	`/journeys/{slug}/nodes/{nodeId}`	ノード削除（エッジ・画像もカスケード）	—

ExperienceNode オブジェクト

{
  "id": 1,
  "journey_id": 1,
  "title": "SNS広告",
  "description": "通勤中にスマホで発見",
  "phase": "認知",
  "emoji": "😐",
  "emotion": 0,
  "x": 50,
  "y": 100,
  "sort_order": 1,
  "created_at": "...",
  "updated_at": "..."
}

emotion: -2 〜 +2 の整数
x, y: Canvas ビュー用座標
phase: Timeline ビューでの列分け用文字列（journey.phases と一致させる）

Experience Edges (接続)

ノード間の有向接続。分岐・合流対応。

Method	Path	Description	Body
GET	`/journeys/{slug}/edges`	エッジ一覧	—
POST	`/journeys/{slug}/edges`	エッジ作成	`{from_node_id, to_node_id, label?}`
PUT	`/journeys/{slug}/edges/{edgeId}`	エッジ更新（label）	`{label}`
DELETE	`/journeys/{slug}/edges/{edgeId}`	エッジ削除	—

ExperienceEdge オブジェクト

{
  "id": 1,
  "journey_id": 1,
  "from_node_id": 1,
  "to_node_id": 2,
  "label": "次に",
  "created_at": "..."
}

Node Images (画像)

ノードに紐づく画像。複数枚 OK。

Method	Path	Description	Body
GET	`/journeys/{slug}/images`	ジャーニー全画像	—
GET	`/journeys/{slug}/nodes/{nodeId}/images`	ノード画像一覧	—
POST	`/journeys/{slug}/nodes/{nodeId}/images`	画像アップロード（複数可）	multipart/form-data (`file` 複数)
PUT	`/journeys/{slug}/images/{imageId}`	キャプション更新	`{caption}`
DELETE	`/journeys/{slug}/images/{imageId}`	画像削除（ファイルも削除）	—

NodeImage オブジェクト

{
  "id": 1,
  "node_id": 1,
  "url": "/uploads/nodes/abc123.png",
  "caption": "",
  "sort_order": 1,
  "created_at": "..."
}

アップロード仕様

対応形式: jpg, jpeg, png, gif, webp
上限: 100MB（複数ファイル合計）
保存先: /opt/try/uploads/nodes/<random>.ext
公開URL: https://try.stagbeetle.group/uploads/nodes/...
multipart フィールド: file（複数指定可、files も受け付け）
戻り値: 作成された画像オブジェクトの配列

エラーレスポンス

{"error": "journey not found"}

Code	意味
200	取得/更新成功
201	作成成功
204	更新/削除成功（ボディ無し）
400	リクエスト不正
404	リソース未発見
500	サーバーエラー

使用例

ジャーニー作成 → ノード追加 → 接続

# 1. ジャーニー作成
curl -X POST https://try.stagbeetle.group/api/v1/journeys \
  -H 'Content-Type: application/json' \
  -d '{"slug":"my-journey","name":"My Journey","description":"テスト"}'

# 2. ノード3つ作成
curl -X POST https://try.stagbeetle.group/api/v1/journeys/my-journey/nodes \
  -H 'Content-Type: application/json' \
  -d '{"title":"認知","phase":"認知","emoji":"😐","x":50,"y":100}'

curl -X POST https://try.stagbeetle.group/api/v1/journeys/my-journey/nodes \
  -H 'Content-Type: application/json' \
  -d '{"title":"検討","phase":"検討","emoji":"🙂","x":280,"y":100}'

curl -X POST https://try.stagbeetle.group/api/v1/journeys/my-journey/nodes \
  -H 'Content-Type: application/json' \
  -d '{"title":"購入","phase":"購入","emoji":"😄","x":510,"y":100}'

# 3. エッジで接続
curl -X POST https://try.stagbeetle.group/api/v1/journeys/my-journey/edges \
  -H 'Content-Type: application/json' \
  -d '{"from_node_id":1,"to_node_id":2}'

curl -X POST https://try.stagbeetle.group/api/v1/journeys/my-journey/edges \
  -H 'Content-Type: application/json' \
  -d '{"from_node_id":2,"to_node_id":3,"label":"購入完了"}'

ノードに複数画像をアップロード

curl -X POST https://try.stagbeetle.group/api/v1/journeys/my-journey/nodes/1/images \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
  -F "file=@photo3.jpg"

ノード位置更新（ドラッグ後）

curl -X PATCH https://try.stagbeetle.group/api/v1/journeys/my-journey/nodes/1/position \
  -H 'Content-Type: application/json' \
  -d '{"x":150,"y":250}'

注意事項

UTF-8必須

リクエストボディは厳密にUTF-8でないと拒否される（400エラー）。Windows等のシェルから日本語を送る場合は文字コードに注意。

文字列フィールドの空値

PUT 時、未指定フィールドは空文字で上書きされる。部分更新は未対応（PATCH /position を除く）。

slug の制約

URL-safe な英数字とハイフンを推奨。重複はジャーニーレベルでは UNIQUE。

ノード位置 (x, y)

ピクセル単位
Canvas は 0,0 が左上
ドラッグ時は PATCH /position を呼ぶと軽量

ファイルパス

アップロードされた画像は /opt/try/uploads/nodes/ に保存
DB には相対URL /uploads/nodes/{filename} で記録
公開URLは https://try.stagbeetle.group/uploads/nodes/...
ジャーニー削除時、関連画像ファイルは自動削除されない（手動削除が必要）

未実装機能

バッチ API（Phase 5 で予定）
インポート/エクスポート（Phase 5 で予定）
ペルソナ管理（Phase 4 で予定）

詳細は README / TODO 参照。