API リファレンス

概要

Periodic Intel APIを利用すると、データ収集ジョブの管理、生成されたレポートの取得、通知の設定などをプログラムから実行できます。このAPIはRESTfulインターフェースを採用しており、リクエストとレスポンスにはJSONを使用します。

バージョニングについて: 現在のAPIにはパスのバージョン接頭辞はありません（例: /v1/）。将来的に破壊的変更が生じた場合はバージョン付きパスへ移行する予定です。変更がある際は事前にお知らせします。

認証 (Authentication)

ほとんどの API は API キー または ユーザーセッションの Bearer トークン で認証できます。 ただし API キー管理 (/api-keys) はユーザーセッション必須 です。

1. ダッシュボードの API Keys 画面にアクセスします。
2. 作成 (Create) をクリックして、新しいAPIキーを生成します。
3. 作成直後に表示されるシークレット（例: msk_xxxx）をコピーして安全に保管してください。再表示はできません。

API キーを使う場合は、以下のいずれかの形式で送信できます。

X-API-Key: msk_your_api_key_here

Authorization: ApiKey msk_your_api_key_here

ダッシュボード内の呼び出しでは、Firebase ID トークンを使った Bearer 認証も利用しています。

APIキーは秘密情報として扱い、公開リポジトリやクライアントサイドのコードには含めないでください。

認証エラー時の挙動:

• 認証情報が存在しない場合は 401 Unauthorized が返ります。
• 無効・失効・期限切れの API キーでは、現在の実装では 400 Bad Request が返ります。
• キーは有効だが対象リソースへのアクセス権限がない場合（他ユーザーのリソースへのアクセス等）は 403 Forbidden が返ります。

ベースURL

https://api.stratum-flow.com

エラーハンドリング

共通エラーフォーマット

エラー発生時は、以下の形式のJSONレスポンスが返ります。

{
  "ok": false,
  "message": "エラーの詳細メッセージ"
}

HTTPステータスコード一覧

エンドポイント

ジョブ (Jobs)

ジョブは、データ収集の指示内容や実行スケジュールを定義します。

GET /jobs

設定済みのジョブ一覧を取得します。1ページあたり 10件（デフォルト）で、カーソルベースのページネーションに対応しています。

Query Parameters:

Response (200 OK):

例:

{
  "ok": true,
  "data": [
    {
      "id": "b0DoFn4h9TKNWHsjdsEd",
      "name": "競合SaaSの動向リサーチi",
      "sourceUrl": "",
      "promptInstruction": "競合・市場・技術トレンドを横断的に調査し、重要な変化とインパクトを要約してください。",
      "intervalMinutes": 1440,
      "timezone": "UTC",
      "status": "paused",
      "running": false,
      "notificationConfigId": null,
      "nextRunAt": "2026-03-29T11:49:00.000Z"
    },
    {
      "id": "6MjSCdVQzTui3SXLAMQn",
      "name": "競合SaaSの動向リサーチh",
      "sourceUrl": "",
      "promptInstruction": "競合・市場・技術トレンドを横断的に調査し、重要な変化とインパクトを要約してください。",
      "intervalMinutes": 1440,
      "timezone": "UTC",
      "status": "paused",
      "running": false,
      "notificationConfigId": null,
      "nextRunAt": "2026-04-05T11:49:00.000Z"
    }
    /* …8 件省略… */
  ],
  "pagination": {
    "nextCursor": "X8ikRFjvXA0U6imnW7X4",
    "hasMore": true
  }
}

POST /jobs

新しいジョブを作成します。

Body (JSON):

Response (200 OK):

PATCH /jobs/:id

ジョブの設定を更新します。指定したフィールドのみが更新されます。

Body (JSON):

Response (200 OK):

POST /jobs/:id/status

ジョブの実行状態（アクティブ／一時停止）を変更します。

Body (JSON):

Response (200 OK):

DELETE /jobs/:id

ジョブを無効化します。ジョブは一時停止状態になり、次回実行スケジュールが解除されます（物理削除ではありません）。

Response (200 OK):

POST /jobs/:id/run

ジョブを即座に実行（手動実行）します。実行はキューに追加され、非同期で処理されます。

Body (JSON):

Response (202 Accepted):

Error (409 Conflict):

{ "ok": false, "message": "Job is already running" }

実行結果は GET /jobs/:jobid/reports または GET /runs?jobId=:id でポーリングして確認できます。

GET /jobs/:id/running

ジョブが現在実行中かどうかを取得します。

Response (200 OK):

レポート (Reports)

ジョブによって生成されたインテリジェンス・レポートです。

GET /jobs/:jobid/reports

特定のジョブに関連するレポート一覧を取得します。最新順で1ページあたり 10件（デフォルト）、カーソルベースのページネーションに対応しています。

Query Parameters:

Response (200 OK):

例:

{
  "ok": true,
  "data": [
    {
      "id": "X8ikR...-177243...",
      "jobId": "X8ikR...",
      "status": "success",
      "subject": "レポート1",
      "summary": "本文...",
      "abstract": null,
      "createdAt": "2026-03-29T12:00:00.000Z"
    },
    /* … */
  ],
  "pagination": {
    "nextCursor": "gU3Ed...-177243...",
    "hasMore": true
  }
}

GET /jobs/:jobid/reports/:reportid

特定のレポート単体の詳細情報を取得します。

Response (200 OK):

GET /runs

実行ログ（Run）の一覧を取得します。最新順で最大 1200件 返ります。

Query Parameters:

Response (200 OK):

通知履歴 (Notifications)

GET /notifications

通知履歴の一覧を取得します。最新順で最大 50件 返ります。

Response (200 OK):

POST /notifications/read-all

すべての未読通知を既読にします。

Response (200 OK):

{ "ok": true, "data": { "success": true } }

トレンド分析 (Trend Analysis)

ジョブに関連するトレンド分析レポート（AIによるタイムライン分析）を取得・生成します。

権限: Starter プラン以上

GET /jobs/:jobid/timeline-report

指定したジョブの最新のトレンド分析レポートを取得します。まだ生成されていない場合は data: null が返ります。

Response (200 OK):

POST /jobs/:jobid/timeline-report/generate

指定したジョブのトレンド分析レポートの生成を非同期で開始します。成功するには、対象ジョブに2件以上の成功済みレポートが必要です。

Response (202 Accepted):

{ "ok": true, "data": { "generating": true } }

生成完了はポーリング（GET /jobs/:jobid/timeline-report）で確認できます。data.status が "generating" から完了状態に変わったタイミングで結果が利用可能になります。

通知設定 (Notification Configs)

Slack、Teams、汎用 Webhook、またはメール宛の外部連携設定を管理します。Starter プラン以上が必要です。

GET /notification-configs

登録済みの通知先設定の一覧を取得します。

Response (200 OK):

POST /notification-configs

新しい通知先を作成します。

Body (JSON):

Response (200 OK):

PATCH /notification-configs/:id

通知先設定を更新します。指定したフィールドのみが更新されます。

Body (JSON):

Response (200 OK):

DELETE /notification-configs/:id

通知先設定を削除します。この設定を参照しているジョブからは自動的に紐付けが解除されます。

Response (200 OK):

{ "ok": true, "data": { "deleted": true } }

POST /notification-configs/:id/test

通知先にテストメッセージを送信します。設定が isActive: false の場合は 400 エラーになります。

Response (200 OK):

{ "ok": true, "data": { "sent": true } }

APIキー管理 (API Keys)

APIキーの管理操作はユーザーセッション（ダッシュボードのログイン状態）でのみ実行可能です。APIキー自体を使って別のAPIキーを管理することはできません。Pro プラン以上が必要です。

GET /api-keys

登録済みのAPIキーの一覧を取得します。最大50件。

Response (200 OK):

POST /api-keys

新しいAPIキーを発行します。シークレット（secret）は作成時のレスポンスにのみ含まれ、以降は取得できません。

Body (JSON):

Response (200 OK):

POST /api-keys/:id/disable

APIキーを無効化します。無効化したキーはすぐに認証に使えなくなりますが、後で再有効化できます。

Response (200 OK):

{ "ok": true, "data": { "disabled": true, "apiKey": { "id": "...", "disabledAt": "2026-03-02T10:00:00.000Z" } } }

POST /api-keys/:id/enable

無効化したAPIキーを再有効化します。期限切れのキーは再有効化しても期限切れのままです。

Response (200 OK):

{ "ok": true, "data": { "enabled": true, "apiKey": { "id": "...", "disabledAt": null } } }

DELETE /api-keys/:id

APIキーを物理削除します。削除したキーは復元できません。

Response (200 OK):

{ "ok": true, "data": { "deleted": true } }

アカウント (Account)

GET /account/usage

現在のアカウントの利用状況（今月のレポート生成数、プラン等）を取得します。

Response (200 OK):

{
  "ok": true,
  "data": {
    "monthlyReportsGenerated": 42,
    "tier": "starter",
    "usageStartAt": "2026-03-01T00:00:00Z",
    "usageEndAt": "2026-03-31T23:59:59Z"
  }
}

データモデル

Job Object

{
  "id": "job_abc123",
  "name": "競合分析",
  "sourceUrl": "https://example.com/news",
  "promptInstruction": "競合他社の最新動向を分析してください",
  "intervalMinutes": 1440,
  "timezone": "Asia/Tokyo",
  "status": "active",
  "running": false,
  "researchMode": "normal",
  "researchModelProfile": "standard",
  "notificationConfigId": "cfg_xyz456",
  "lastRunAt": "2026-03-02T10:00:00.000Z",
  "nextRunAt": "2026-03-03T10:00:00.000Z"
}

Report Object

{
  "id": "rpt_def456",
  "jobId": "job_abc123",
  "status": "success",
  "subject": "競合分析レポート 2026-03-02",
  "summary": "今週の主なトピックは...",
  "abstract": "要約テキスト（存在する場合）",
  "sources": [
    {
      "index": 1,
      "url": "https://example.com/source"
    }
  ],
  "createdAt": "2026-03-02T10:05:00.000Z"
}

Run Object

{
  "id": "job_abc123-1709380000000",
  "jobId": "job_abc123",
  "status": "success",
  "startedAt": "2026-03-02T10:00:00.000Z",
  "finishedAt": "2026-03-02T10:04:58.000Z",
  "durationMs": 298000,
  "triggeredBy": "manual",
  "errorCategory": null,
  "errorMessage": null
}

Notification Config Object

{
  "id": "cfg_xyz456",
  "provider": "slack",
  "name": "開発チーム通知",
  "webhookUrlMasked": "https://hooks.slack.com/...****",
  "destinationMasked": "https://hooks.slack.com/...****",
  "isActive": true,
  "createdAt": "2026-02-01T00:00:00.000Z",
  "updatedAt": "2026-02-15T12:30:00.000Z"
}

Timeline Report Object

{
  "id": "job_abc123",
  "jobId": "job_abc123",
  "subject": "競合動向トレンドレポート",
  "body": "過去N件のレポートを分析した結果...",
  "status": "done",
  "reportCount": 12,
  "createdAt": "2026-03-01T08:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}