Sky API Reference

プロダクトレビュー＆チェックツール「Sky」の REST API。

基本情報

Base URL: https://sky.stagbeetle.group/api/v1
Format: JSON (UTF-8必須)
レスポンス形式: {"data": ...}（204は空）
エラー形式: {"error": "message"}
姉妹システム: Fudo / Love / Try

概念

Product (1プロダクト)
  ├─ ProductImage (画像 + アノテーション)
  │     └─ ImageAnnotation (赤枠 + テキスト指示)
  ├─ Whiteboard (ホワイトボード)
  │     └─ WhiteboardItem (image / text / arrow)
  └─ Model3D (3Dモデル, GLB / FBX)

Products

Method	Path	Description	Body
GET	`/products`	プロダクト一覧	—
POST	`/products`	プロダクト作成	`{slug, name, description?, cover_image_url?}`
GET	`/products/{slug}`	プロダクト取得	—
PUT	`/products/{slug}`	プロダクト更新	`{name, description, cover_image_url}`
DELETE	`/products/{slug}`	プロダクト削除（カスケード）	—

Images (画像チェッカー)

Method	Path	Description	Body
GET	`/products/{slug}/images`	画像一覧	—
POST	`/products/{slug}/images`	画像アップロード（複数可）	multipart (`file` 複数)
PUT	`/products/{slug}/images/{imageId}`	キャプション更新	`{caption}`
DELETE	`/products/{slug}/images/{imageId}`	画像削除	—

ProductImage オブジェクト

{
  "id": 1,
  "product_id": 1,
  "url": "/uploads/images/abc123.png",
  "original_name": "screenshot.png",
  "caption": "",
  "width": 1920,
  "height": 1080,
  "sort_order": 1,
  "created_at": "...",
  "updated_at": "..."
}

対応形式: jpg / jpeg / png / gif / webp
上限: 100MB（複数合計）
画像サイズ（width/height）は自動取得

Image Annotations (赤枠注釈)

座標は画像に対する相対値（0〜1）で保存。ズームに依存しない。

Method	Path	Description	Body
GET	`/products/{slug}/images/{imageId}/annotations`	注釈一覧	—
POST	`/products/{slug}/images/{imageId}/annotations`	注釈作成	`{x, y, width, height, text?, color?}`
PUT	`/products/{slug}/annotations/{annId}`	注釈更新	全フィールド
DELETE	`/products/{slug}/annotations/{annId}`	注釈削除	—

ImageAnnotation オブジェクト

{
  "id": 1,
  "image_id": 1,
  "x": 0.1,
  "y": 0.2,
  "width": 0.3,
  "height": 0.15,
  "text": "ここを修正",
  "color": "#ef4444",
  "created_at": "...",
  "updated_at": "..."
}

x, y, width, height: 0〜1 の相対値（画像左上が原点）
color: デフォルト #ef4444（赤）
ブラウザ側で「焼き込みDL」ボタンがあり、Canvas APIで注釈を画像に合成してPNG出力可能

Whiteboards (ホワイトボード)

ボード管理

Method	Path	Description	Body
GET	`/products/{slug}/whiteboards`	ボード一覧	—
POST	`/products/{slug}/whiteboards`	ボード作成	`{name}`
PUT	`/products/{slug}/whiteboards/{boardId}`	ボード名変更	`{name}`
DELETE	`/products/{slug}/whiteboards/{boardId}`	ボード削除（カスケード）	—

ボードアイテム

Method	Path	Description	Body
GET	`/products/{slug}/whiteboards/{boardId}/items`	アイテム一覧	—
POST	`/products/{slug}/whiteboards/{boardId}/items`	アイテム作成	WhiteboardItem
PUT	`/products/{slug}/whiteboards/items/{itemId}`	アイテム更新	WhiteboardItem
DELETE	`/products/{slug}/whiteboards/items/{itemId}`	アイテム削除	—

画像アップロード（ボード用）

Method	Path	Description	Body
POST	`/products/{slug}/whiteboards/upload-image`	画像アップロード	multipart (`file` 複数)

戻り値は [{url, original_name}]。アイテム作成は別途 POST /items で type=image + image_url を指定。

WhiteboardItem オブジェクト

{
  "id": 1,
  "whiteboard_id": 1,
  "type": "image",
  "x": 100,
  "y": 200,
  "width": 240,
  "height": 180,
  "image_url": "/uploads/whiteboard/abc.png",
  "text": "",
  "color": "#fde68a",
  "from_item_id": null,
  "to_item_id": null,
  "z_order": 0,
  "created_at": "...",
  "updated_at": "..."
}

type の種類

type	用途	主要フィールド
`image`	画像カード	image_url, x, y, width, height
`text`	テキスト/付箋	text, color, x, y, width, height
`arrow`	矢印接続	from_item_id, to_item_id

3D Models (3Dモデルビューア)

Method	Path	Description	Body
GET	`/products/{slug}/models`	モデル一覧	—
POST	`/products/{slug}/models`	モデルアップロード	multipart (`file`, `name?`)
PUT	`/products/{slug}/models/{modelId}`	名前/説明更新	`{name, description}`
DELETE	`/products/{slug}/models/{modelId}`	モデル削除	—

Model3D オブジェクト

{
  "id": 1,
  "product_id": 1,
  "name": "Character",
  "file_url": "/uploads/models/abc123.glb",
  "file_format": "glb",
  "original_name": "character.glb",
  "file_size": 5242880,
  "description": "",
  "created_at": "...",
  "updated_at": "..."
}

フォーマット対応

形式	ビューア	テクスチャ	備考
.glb / .gltf	model-viewer (Google)	対応 (埋め込み)	推奨
.fbx	three.js + FBXLoader	グレー表面固定	形状確認用

上限: 50MB
GLBはテクスチャ/マテリアル/ライティング全対応
FBXは MeshStandardMaterial({ color: 0x9ca3af }) でグレー表示、自動スケーリング

エラーコード

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

使用例

画像アップ → 注釈追加

# 画像アップロード
curl -X POST https://sky.stagbeetle.group/api/v1/products/my-product/images \
  -F "file=@screenshot.png"

# 注釈追加（相対座標）
curl -X POST https://sky.stagbeetle.group/api/v1/products/my-product/images/1/annotations \
  -H 'Content-Type: application/json' \
  -d '{"x": 0.1, "y": 0.2, "width": 0.3, "height": 0.15, "text": "ここを修正"}'

ホワイトボード作成 → 画像配置

# ボード作成
curl -X POST https://sky.stagbeetle.group/api/v1/products/my-product/whiteboards \
  -H 'Content-Type: application/json' \
  -d '{"name": "Design Review"}'

# 画像アップロード
curl -X POST https://sky.stagbeetle.group/api/v1/products/my-product/whiteboards/upload-image \
  -F "file=@mockup.png"
# -> {"data": [{"url": "/uploads/whiteboard/abc.png", "original_name": "mockup.png"}]}

# 画像アイテム作成
curl -X POST https://sky.stagbeetle.group/api/v1/products/my-product/whiteboards/1/items \
  -H 'Content-Type: application/json' \
  -d '{"type": "image", "x": 100, "y": 100, "width": 300, "height": 200, "image_url": "/uploads/whiteboard/abc.png"}'

3Dモデルアップロード

curl -X POST https://sky.stagbeetle.group/api/v1/products/my-product/models \
  -F "file=@character.glb" -F "name=Character"