システムを Marcomm AI に接続する

1. 1
   アクセスを申請する

   お使いのシステムの概要と、必要なデータを選んで入力します。申請は審査のうえ承認されます。

2. 2
   キーを作成する

   承認後、「設定 > API」でキーを作成します。キーは一度だけ表示されるため、お使いのシステムに保管してください。

3. 3
   リクエストを送る

   Authorization ヘッダーにキーを付けて、下記のエンドポイントを呼び出します。

リクエスト例

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

リクエストごとに、キーを Bearer トークンとして送信します。個人キーは作成した本人として動作するため、その人の名義で承認の閲覧と判断ができます。ワークスペースキーは管理者が作成し、読み取り専用です。キーには有効期限と IP アドレス制限を設定でき、ローテーションもできます。ローテーション後も、古いキーは 24 時間使えます。

各キーには、申請が承認されたスコープのみが付与されます。

news

ニュースダイジェスト、記事、媒体。

crisis

重要ニュースと危機インシデント。

approvals

承認待ちの項目の取得と、個人キーによる承認または却下。

content

プレスリリースとブログ記事の読み取り。

パスは /api/v1 で始まります。読み取り用エンドポイントは GET を使い、クエリパラメータを受け取ります。レスポンスは {"data": ...} 形式の JSON です。

対象の項目に {"decision": "approve"} または {"decision": "reject", "comment": "..."} を送信します。却下にはコメントが必要です。判断はアプリや Slack と同じルールに従い、キーの所有者の名義で記録されます。確認が必要な表現が本文に含まれる場合は、警告とともに 409 confirmation_required が返ります。"force": true を付けて再送信してください。

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

制限はワークスペースごとに、1 分あたりと 1 日あたり（UTC）で設定されます。レスポンスには下記のヘッダーが付きます。制限を超えると Retry-After 付きで 429 が返ります。上限の引き上げは「設定 > API」から申請してください。担当チームが審査します。

X-RateLimit-Limit

1 分あたりの許可リクエスト数。

X-RateLimit-Remaining

現在の 1 分間で残っているリクエスト数。

X-RateLimit-Reset

1 分間のウィンドウがリセットされる Unix 時刻。

X-RateLimit-Day-Limit

1 日あたりの許可リクエスト数。

X-RateLimit-Day-Remaining

今日の残りリクエスト数。

Retry-After

再試行までの待機秒数。429 のときのみ付きます。

エラーは {"error": {"code": ..., "message": ...}} 形式の JSON で返ります。

アラート、承認依頼、朝のブリーフィングは、お使いのシステムへプッシュすることもできます。「設定 > API > Webhook」で送信先を追加してください。各リクエストは、event（alert、approval、briefing）、workspace、title、text、url、data、sentAt の各フィールドを持つ JSON です。承認依頼には data.kind（press_release、blog、event）と data.id が含まれ、API 経由での読み取りと判断に使えます。

各リクエストには署名が付きます。署名シークレットでリクエスト本文（生のまま）の HMAC-SHA256 を計算し、sha256=<hex> 形式の X-Marcomm-Signature ヘッダーと比較してください。一致しないリクエストは拒否します。

Node.js での Webhook の検証

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}