テーマ
External API(有料・API・MCP オプション)
組織のプロジェクト・監視ユニット・カメラ・インシデント・対応報告書を外部システムから参照・操作するためのREST APIです。/alert(アラート受信用Webhook)とは別のAPIで、利用にはAPI・MCP オプションの契約(基本料 月額1,500円・税込・Basic・Business・Premium)が必要です。基本料に含まれる回数と従量の計算例は料金ページを参照してください。
認証
X-API-Key ヘッダーに、組織単位で発行したAPIキーを指定します。キーはconsole(console.sisa.jp)の「APIキー」画面から発行できます(組織のowner/adminのみ発行可能)。
X-API-Key: sisak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- レート制限: 120 req/分(キー単位)
- 基本料に含まれる回数: Basic 1,000・Business 3,000・Premium 5,000 コール/月。超えた分は 1,000 コールごとに 300 円(1 コールでも超えると 1,000 コール分)
- 月の上限: 既定 100,000 コール。組織のowner/adminが console で込みの回数〜1,000,000 の間で変えられます(利用量と月の上限)。上限到達時は
429 USAGE_LIMIT_EXCEEDED - 数えるのは成功した呼び出しだけです。
GET /v1/usage(今月の回数・残り・込みの回数・単価)は数えません
コール数を抑える書き方
定期的に見に行く処理(AI エージェントの見回り・台帳への同期など)は、毎回すべてを取り直さず、前回から変わったものだけを取るとコール数を抑えられます。呼び出しは 1 回ごとに数えるので、一覧 1 回で 100 件取っても 1 コールです。
| 見たいもの | 書き方 |
|---|---|
| 対応中のインシデント | GET /v1/incidents?status=in_progress&limit=100 を 1 回。一覧の各件は 1 件の取得(GET /v1/incidents/{id})と同じ中身なので、1 件ずつ取り直す必要はありません。updated_at が前回と同じ件は変わっていません |
| 新しい・直された報告書 | GET /v1/reports?updated_since=<前回取った時刻>。変わった報告書だけが返ります |
| 傾向分析 | 毎朝 1 回作り直すだけなので、1 日 1 回で足ります。過去の版は GET /v1/incidents/trends/history?since=<前回の最後の generated_at> で増えた分だけ |
| 月ごとの件数 | 過去の月はほとんど変わりません(変わるのはプロジェクトをアーカイブしたときなど)。ふだん取り直すのは今月の分だけ(from・to に今月の YYYY-MM) |
| 届いたアラート | GET /v1/alerts/{alert_id}(イベント Webhook の alert.received が送る alert_id)。インシデントの応答の alert_id からも辿れます |
| 残りの回数 | GET /v1/usage(数えません)。remaining が少なくなったら間隔を空ける |
- 見に行く間隔の目安: 5 分おきに 3 コールで月およそ 26,000 コール、30 分おきなら 4,300 コールほどです
- 起きたときだけ動く: イベント Webhook を使うと、アラートやインシデントが起きた瞬間に SISA から通知が届きます(送信はコールに数えません)。通知の ID で必要なものだけ取りに来れば、見に行く処理そのものが要らなくなります
429 RATE_LIMITED(キーごとに毎分 120 回)はRetry-Afterの秒数だけ待って送り直し、429 USAGE_LIMIT_EXCEEDED(月の上限)は送り直さないでください
報告書を取り出す(自社様式の報告書を作る)
SISA の対応報告書を外部のシステムに取り込み、自社の様式に合わせた報告書を作るための口です。
- 一覧
GET /v1/reports: 新しく変わった順に、件名・発生時刻・作成者・写真の枚数などの要約を返します (本文と写真は含みません)。updated_sinceに前回取った時刻を入れると、その後に作られた報告書と、本文や写真が変わった報告書だけが取れます。project_id・occurred_from・occurred_toでも絞れます - 1 件の全部
GET /v1/reports/{report_id}: 原因・対応内容・対応結果・再発防止策・備考などの全欄と、写真を全件(報告書に並んだ順・撮った人と時刻つき)返します - 写真
download_url(原本)・thumbnail_url(小さい画像): 1 件の取得で返った URL をそのまま開きます
| 項目 | 内容 |
|---|---|
| API コール | 一覧・1 件の取得はそれぞれ 1 回。写真の取り出しは数えません |
| 写真の URL | 返してから 1 時間 有効・API キーは不要。切れたら 1 件を取り直して新しい URL を使います |
| 写真の上限 | API キーごとに 1 時間あたり 3,000 枚。超えると 429 と Retry-After(秒) |
| 読めるキー | 読み取り専用(read_only)のキーでも取れます |
| 対象 | アーカイブしていないプロジェクトの報告書 |
写しをお手元に持つ前提で
報告書は、プロジェクトをアーカイブしてから 30 日で削除 されます(一覧からはアーカイブした時点で外れます)。取り込んだ報告書と写真は、お手元のシステムに保存してください。
取り扱いの注意
- 作成者・撮った人の氏名(SISA での表示名)が含まれます。取り込み先での扱いにご注意ください
- API キーを失効させても、それまでに返した写真の URL は期限(1 時間)まで開けます
下のSwagger UIの「Authorize」からキーを入力すると、この画面から直接APIを試せます。