Public API

対象読者：SDK config の読み取りと feedback ingestion を確認する SDK 開発者と backend 開発者。

public API は contracts version 0.4.0-alpha.1 に対応し、ローカルでは http://localhost:4000 で提供されます。SDK config の読み取り、feedback report の書き込み、同意で制限された添付アップロードを受け付けます。認証は X-Project-Key です。

ルート

Method	Path	用途
`GET`	`/healthz`	Process liveness のみ。
`GET`	`/readyz`	PostgreSQL と object storage の readiness。
`GET`	`/v1/sdk/config?locale=zh-CN\|en\|ja`	ローカライズされた SDK config、privacy text、category、attachment limits、未選択の同意 defaults。
`POST`	`/v1/feedback/reports`	プレイヤー主導の feedback report と consent snapshot を作成します。
`POST`	`/v1/feedback/reports/{feedback_id}/attachments`	screenshot や recent log など、同意で制限された添付をアップロードします。

Liveness、readiness、ブラウザアクセス

GET /healthz は外部依存関係を確認しません。認証不要の GET /readyz は PostgreSQL と object storage の両方を hard dependency として扱います。2 つの component がともに ready の場合だけ 200 ready を返し、どちらかが失敗すると 503 unavailable を返します。response は Cache-Control: no-store を使い、raw dependency error、endpoint、bucket name、credential を公開しません。

Alpha の Public API には意図的にブラウザ CORS policy がありません。対応する consumer は native Godot game と non-browser tooling です。ブラウザ向け API として扱ったり、Admin API の状態から Public API の状態を推測したりしないでください。

最小例

curl -X POST "http://localhost:4000/v1/feedback/reports" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: ja" \
  -H "X-Project-Key: enb_pk_xxx" \
  -H "Idempotency-Key: godot-demo-uuid-002" \
  -d '{
  "client_report_id": "godot-demo-uuid-002",
  "trigger_source": "button",
  "category": "suggestion",
  "description": "マップマーカーはコントラストが高い方が見やすいです。",
  "content_language": "ja",
  "player": {
    "id_hash": "sha256:337180dda29405211bf7a37ea531367110370dc54db2298fcf4450f1749badb3"
  },
  "app": {
    "environment": "test",
    "release": "0.1.0",
    "build_id": "dev-build-001",
    "engine": "godot",
    "engine_version": "4.x"
  },
  "game_context": {
    "scene": "res://scenes/hub.tscn",
    "level": "hub",
    "extra": {}
  },
  "breadcrumbs": [],
  "consents": {
    "privacy_notice_version": "v1",
    "locale": "ja",
    "player_confirmed_submit": true,
    "screenshot_upload": false,
    "recent_logs_upload": false,
    "contact_upload": false,
    "submitted_at": "2026-06-10T01:05:02Z"
  },
  "locale": "ja",
  "device": {
    "platform": "macos",
    "locale": "ja"
  }
}'

成功時は 202 Accepted と feedback_id、multipart 添付 endpoint が返ります。

サーバー既定値

必須フィールドは client_report_id、trigger_source、category、description、consents です。実行環境・バージョン・ビルド・エンジンは app、プラットフォームと端末情報は device、任意のプレイヤー識別子と連絡先は player に入れます。実行情報を省略すると unknown、エンジンは godot になります。UI言語は locale、Accept-Language、プロジェクトの既定言語、en の順で解決し、content_language と同意の言語は別です。重複したトップレベルの実行情報・連絡先・ui_locale は拒否します。最新SDKを使用し、旧Alphaデータや形式は移行しません。

よくある間違い

feedback 作成時に Idempotency-Key を省略しないでください。
添付の再試行には安定した添付単位の Idempotency-Key（1～120 文字）を使用してください。同じキーで異なる内容を送ると 409 になります。
consents.recent_logs_upload が false のときは recent_logs を送らないでください。送られた場合、サーバーはインラインログを破棄し、recent_logs_dropped: true を記録します。
保存済み同意がスクリーンショットを許可していない場合、screenshot 添付をアップロードしないでください。
例の player_id_hash を再利用しないでください。送信前に自分の player identifier を hash 化または仮名化してください。
Project Key を /admin/v1/* Admin API endpoint に使わないでください。

次のステップ

Admin APIで受理済みフィードバックを確認してください。

リソース制限と起動設定ポリシーはトラブルシューティングを参照してください。