改善案

改善案は、ワークフロー / コンテキスト・パックに対するテキスト中心の提案です。パックを読める人なら誰でも作成でき、更新できるのは投稿者だけ、解決できるのはパックの所有者だけです。ライフサイクルと権限モデルは 改善案 を参照してください。

accountId は認証トークンから解決され、リクエストでは渡しません。アクティブなワークスペースはトークンまたは workspaceId クエリパラメータから決まります。改善案の作成は 5 credits、一覧は 2 credits、取得・更新・解決はそれぞれ 1 credit を消費します。

改善案の作成

POST /v1/suggestions
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "reference": "@market-research",
  "title": "Add review step",
  "content": "Add a final human review before publishing."
}

reference はパック ID、@alias、共有 URL、ハブ URL のいずれかです。title と content は必須です。201 を返します。作成時点のパックの内容がスナップショットとして保存されます。1アカウントあたり1日20件まで作成できます。

改善案の一覧

POST /v1/suggestions/search
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "owner": true,
  "statuses": ["open"]
}

検索ボディは CLI のフラグに対応します。

• owner と reference を省略すると、自分が送信した 改善案を一覧します。
• owner: true は自分の 受信箱(自分が所有するパックへの改善案)を返します。
• reference は 特定のパック向け の改善案を返します(author でさらに絞り込み可)。

statuses は open, applied, declined, archived で絞り込みます。page でページ送り(ページサイズ20)、includeSnapshots で保存されたパック内容を含められます。レスポンスには suggestions、totalCount、page、pageSize が含まれます。

一覧レスポンスの各改善案の content は短縮されたプレビューです。全文は GET /v1/suggestions/:id で取得します(パックの outline → 全文と同じ考え方)。

改善案の取得

curl "https://api.epismo.ai/v1/suggestions/$SUGGESTION_ID?includeSnapshot=true" \
  -H "authorization: Bearer $EPISMO_TOKEN"

includeSnapshot=true を付けると、保存されたパックの内容がレスポンスに含まれます。デフォルトでは省略されます。

改善案の更新

PATCH /v1/suggestions/:id
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "title": "Add review step",
  "content": "Please add a reviewer approval step before publish."
}

改善案のタイトルや本文を更新できるのは投稿者だけです。

改善案の解決

PATCH /v1/suggestions/:id/resolve
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "status": "applied"
}

status は open, applied, declined, archived のいずれかです。改善案を解決できるのはパックの所有者だけです。解決はステータスを変えるだけなので、受け入れる場合はまずパック更新で実際の変更を反映してください。

同じハンドラーは /v1/packs/suggestions プレフィックス配下にもマウントされています(/v1/packs/suggestions、/v1/packs/suggestions/search、/v1/packs/suggestions/:id、/v1/packs/suggestions/:id/resolve)。