レポート

レポート（report） は固定されたドキュメントです。テンプレートを、フィルタ（ワークスペース・プロジェクト・ユーザー・タグ・日付範囲）の集合で、ある固定期間に対してレンダリングしたものです。レンダリングはレポートの作成・編集時に同期的に行われ、生成された Markdown は不変かつバージョン管理されたスナップショットとして保存されます。そのため、ドキュメントは閲覧者・公開共有・配信されたコピーの足元で変化することはありません。

レポートは作成したユーザーが所有します。相対的な日付範囲（this_week など）や生成日は、レンダリング時に所有者のタイムゾーンで解決されます。日付と時刻を参照してください。

レポートオブジェクト

フィールド	型	説明
`id`	string	一意の識別子。
`name`	string	表示名（1〜100 文字）。
`ownerUserId`	string	レポートを作成したユーザー。
`templateId`	string	このレポートにレンダリングしたテンプレート。外部キーではなく、テンプレートが削除されてもレポートは残ります。
`filters`	object	解決済みのフィルタ集合（filters オブジェクトを参照）。保存される `dateRange` は常に絶対値。
`note`	string \| null	`{{ report.note }}` でレンダリング本文に追記される自由記述の Markdown（20000 文字以下）。
`totalMinutes`	integer \| null	現在バージョンのエントリの合計分。この値の追跡前にレンダリングされたレポートは `null`（再レンダリングまで表示）。
`snapshotProjectIds`	string[] \| null	現在のスナップショットにエントリが現れる、重複なしのプロジェクト ID。レンダリング時に取得され、Send-to ACL を駆動します。`null` はスコープ不明（この取得の追加前にレンダリング）を意味します。レポートの送信を参照。ワイヤには出力されますが `@spantail/core` の型付き `reportSchema` には含まれないため、ワイヤ専用の追加フィールドとして扱ってください。
`version`	integer	現在のバージョン。作成時に `1`、編集ごとに +1。
`reportContentId`	string	現在のコンテンツバージョンの ID — コンテンツスコープのリソース（そのバージョンのディスカッション）のキー。
`renderedMarkdown`	string	現在バージョンのレンダリング済みドキュメント。システム生成の YAML フロントマター（来歴）に、Liquid でレンダリングした本文が続きます。
`createdAt`	string	ISO 8601 の作成時刻。
`updatedAt`	string	ISO 8601 の最終更新時刻。

一覧のペイロードでは reportContentId と renderedMarkdown は省略されます。 GET /reports/:id でオンデマンドに取得してください。

filters オブジェクト

フィールド	型	必須	説明
`workspaceIds`	string[]	はい	1〜20 のワークスペース。クロスワークスペースのレポートは呼び出し元のメンバーシップの和集合に限定されます。
`projectIds`	string[]	いいえ	絞り込み対象のプロジェクト（最大 50）。
`userIds`	string[]	いいえ	含める作成者（最大 50）。省略するとレポートは呼び出し元自身のエントリのみになります — これが既定で、Web アプリは常にこの挙動です。指定した作成者も呼び出し元のアクセス権の範囲に限定されます（読めるエントリのみ含められます）。
`tags`	string[]	いいえ	最大 20 件のタグ。いずれかを持つエントリが一致。
`dateRange`	object \| string	はい	ワイヤ上はプリセット文字列か絶対範囲。保存済みレポートでは常に絶対値の `{ from, to }`。

dateRange は プリセット（today、yesterday、last_7_days、last_30_days、this_week、 last_week、this_month、last_month のいずれか。サーバー側で所有者のタイムゾーンで解決。週は月曜始まり）か、絶対範囲 { "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }（両端含む。from ≤ to、最大 366 日）を受け付けます。いずれを送っても、保存されるレポートは解決済みの絶対範囲を保持します。

レポートの一覧

GET /api/v1/reports scope: read

レポートのメタデータ（本文なし）を新しい順で返します。既定では呼び出し元自身のレポートを読みます。インスタンス管理者は ownerUserId で他ユーザーの集合を、ワークスペースの管理者・オーナーは workspaceId で単一ワークスペースのレポート（そのワークスペースだけにスコープされたもの）を読めます。所有者自身の一覧では、所有者がもはや完全には所属しないワークスペースを持つレポートの totalMinutes は null に伏せられます。

クエリパラメータ

名前	型	必須	説明
`ownerUserId`	string	いいえ	インスタンス管理者専用: このユーザーのレポートを読む。
`workspaceId`	string	いいえ	ワークスペース管理者・オーナー: このワークスペースの単一ワークスペースレポートを読む。
`templateId`	string	いいえ	テンプレートで作成したレポートに絞り込み。
`projectId`	string	いいえ	プロジェクトにスコープされたレポートに絞り込み。
`from`	string	いいえ	期間がこの日付以降に重なるレポートを残す `YYYY-MM-DD`。
`to`	string	いいえ	期間がこの日付以前に重なるレポートを残す `YYYY-MM-DD`。
`limit`	integer	いいえ	ページサイズ 1〜200。省略すると絞り込み後の全件。
`offset`	integer	いいえ	スキップ行数（既定 0）。

curl
Response

curl "https://<your-instance>/api/v1/reports?templateId=tpl_weekly&limit=50" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

[
  {
    "id": "rep_q2",
    "name": "Website — week of Jun 22",
    "ownerUserId": "usr_ana",
    "templateId": "tpl_weekly",
    "filters": {
      "workspaceIds": ["wrk_demo"],
      "projectIds": ["prj_site"],
      "dateRange": { "from": "2026-06-22", "to": "2026-06-28" }
    },
    "note": null,
    "totalMinutes": 540,
    "snapshotProjectIds": ["prj_site"],
    "version": 1,
    "createdAt": "2026-06-28T09:30:00.000Z",
    "updatedAt": "2026-06-28T09:30:00.000Z"
  }
]

使用中のテンプレート ID 一覧

GET /api/v1/reports/template-ids scope: read

呼び出し元がレポートを持つ、重複なしのテンプレート ID を返します。すべてのレポートを読み込まずに、UI が関連するテンプレートのタブを表示できます。

["tpl_weekly", "tpl_monthly"]

レポートのプレビュー

POST /api/v1/reports/preview scope: read

レポートを 保存せずに レンダリングします。作成ダイアログのライブプレビュー用です。作成と同じメンバーシップ・テンプレート検証と同じレンダリングを実行するため、プレビューは保存される内容と一致します。書き込みは行われないので read スコープで十分です。

リクエストボディはレポートの作成と同一です。

curl
Response

curl -X POST "https://<your-instance>/api/v1/reports/preview" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website — this week",
    "templateId": "tpl_weekly",
    "filters": {
      "workspaceIds": ["wrk_demo"],
      "projectIds": ["prj_site"],
      "dateRange": "this_week"
    }
  }'

{
  "content": "---\nname: Website — this week\n...\n---\n\n# Website — this week\n...",
  "totalMinutes": 540,
  "entryCount": 12,
  "projectCount": 1,
  "suggestedName": "Website — this week",
  "suggestedNote": ""
}

suggestedName と suggestedNote は、テンプレートの nameTemplate / noteTemplate をこのスコープと期間でレンダリングした結果 — 作成フォームが初期値として埋める値です。テンプレートにその初期値が無い場合は両方とも空になります。

レポートの作成

POST /api/v1/reports scope: write

ドキュメントをレンダリングし、バージョン 1 として保存します。呼び出し元は filters.workspaceIds のすべてのワークスペースに所属している必要があります。テンプレートは存在し、かつ有効でなければなりません。無効なテンプレートは 400 を返します。テンプレートのレンダリングエラーも 400 を返すため、レンダリング不能な状態でレポートが保存されることはありません。

リクエストボディ

フィールド	型	必須	説明
`name`	string	はい	表示名（1〜100 文字）。
`templateId`	string	はい	レンダリングするテンプレート。
`filters`	object	はい	フィルタ集合（filters オブジェクトを参照）。
`note`	string	いいえ	本文に追記する自由記述の Markdown（20000 文字以下）。空文字は `null` に丸められます。

curl
Response

curl -X POST "https://<your-instance>/api/v1/reports" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website — week of Jun 22",
    "templateId": "tpl_weekly",
    "filters": {
      "workspaceIds": ["wrk_demo"],
      "projectIds": ["prj_site"],
      "dateRange": { "from": "2026-06-22", "to": "2026-06-28" }
    }
  }'

{
  "id": "rep_q2",
  "name": "Website — week of Jun 22",
  "ownerUserId": "usr_ana",
  "templateId": "tpl_weekly",
  "filters": {
    "workspaceIds": ["wrk_demo"],
    "projectIds": ["prj_site"],
    "dateRange": { "from": "2026-06-22", "to": "2026-06-28" }
  },
  "note": null,
  "totalMinutes": 540,
  "snapshotProjectIds": ["prj_site"],
  "version": 1,
  "reportContentId": "rct_q2v1",
  "renderedMarkdown": "---\nname: Website — week of Jun 22\n...\n---\n\n# ...",
  "createdAt": "2026-06-28T09:30:00.000Z",
  "updatedAt": "2026-06-28T09:30:00.000Z"
}

201 Created を返します。

レポートの取得

GET /api/v1/reports/:id scope: read

renderedMarkdown を含む単一のレポートを返します。読み取れるのは、所有者、インスタンス管理者、または単一ワークスペースレポートのそのワークスペースの管理者・オーナーです（レポートが厳密に 1 つのワークスペースにスコープされている場合のみ。複数ワークスペースのレポートはインスタンス管理者専用のまま）。所有者にとってレンダリング本文はワークスペースデータであり、いずれかのフィルタ対象ワークスペースのメンバーシップを失うとアクセスは取り消されます。それ以外は 404 を返します。

レポートの更新

PATCH /api/v1/reports/:id scope: write

所有者のみ。編集はレポートのフィールドを変更し、ドキュメントを 再レンダリング して、新しい不変のコンテンツバージョンを追加します。version は 1 つ増えます。リクエストボディは作成と同じ形（name・ templateId・filters をすべて送信）です。GET /:id と同じゲートが適用されます。所有者はすべてのフィルタ対象ワークスペースに所属している必要があり、テンプレートは有効でなければならず、レンダリングエラーは 400 を返します。

curl -X PATCH "https://<your-instance>/api/v1/reports/rep_q2" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website — week of Jun 22 (final)",
    "templateId": "tpl_weekly",
    "filters": {
      "workspaceIds": ["wrk_demo"],
      "projectIds": ["prj_site"],
      "dateRange": { "from": "2026-06-22", "to": "2026-06-28" }
    }
  }'

レポートの削除

DELETE /api/v1/reports/:id scope: write

所有者のみ。共有と配信（それぞれが固定コピーを保持）はレポート行とともにカスケード削除されます。 204 No Content を返します。

受信者

GET /api/v1/reports/:id/recipients scope: read

所有者のみ。送信の候補受信者を返します。レポートのワークスペース全体のメンバーの和集合（すでにそのデータに資格のある人）から送信者を除き、snapshotProjectIds に取得された すべて のプロジェクトを読める人に絞り込みます（ワークスペースの管理者・オーナーは任意のプロジェクトを読め、それ以外は各プロジェクトのメンバーである必要があります）。未割り当て/自身のエントリのみのレポートにはプロジェクト制限はありません。snapshotProjectIds が null（スコープ不明）の場合、再レンダリングするまで誰も対象になりません。

[
  { "id": "usr_bo", "name": "Bo", "email": "bo@example.com", "imageUrl": null }
]

レポートの送信

POST /api/v1/reports/:id/send scope: write

所有者のみ。レポートの現在の 不変バージョン を各受信者の受信トレイに届けます。各受信者は受信者の候補集合に含まれている必要があり、送信でデータを見られる範囲を広げることはできません。対象外の ID は 400 を返します。各配信は送信されたバージョンを参照するため、後で編集（新しいバージョンの追加）があっても受信者は送られた内容を保持します。レポートを削除すると配信も削除されます。

リクエストボディ

フィールド	型	必須	説明
`recipientUserIds`	string[]	いいえ	最大 50 の受信者。既定は `[]`。
`sendToSelf`	boolean	いいえ	送信者自身の受信トレイにもコピーを届ける。既定は `false`。
`message`	string	いいえ	受信者向けの短いメッセージ（1000 文字以下）。

受信者か sendToSelf のいずれかが必須です。

curl
Response

curl -X POST "https://<your-instance>/api/v1/reports/rep_q2/send" \
  -H "Authorization: Bearer spantail_pat_yourtoken" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientUserIds": ["usr_bo"],
    "message": "Here is this week'\''s site report."
  }'

{ "delivered": 1 }

201 Created を返します。delivered はチームメイトの受信者のみを数え、自身へのコピーは数えません。

送信履歴

GET /api/v1/reports/:id/sends scope: read

レポートの送信履歴 — 送信バッチごとに 1 件、新しい順です。読み取りアクセスは受信者や共有と同じ（オーナー、インスタンス管理者、またはそのレポートのワークスペースの管理者）です。readCount は受信者自身の既読状態で、オーナー以外には 0 に伏せられます。管理者が読んでも、単一の受信者がその送信を開いたかどうかは分かりません。

curl
Response

curl "https://<your-instance>/api/v1/reports/rep_q2/sends" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

[
  {
    "id": "snd_1",
    "createdAt": "2026-07-10T09:42:05.000Z",
    "message": "Here is this week's site report.",
    "recipientNames": ["Bo", "Carol"],
    "recipientCount": 2,
    "readCount": 1
  }
]