API tích hợp bên ngoài (chỉ đọc)

外部のシステムが、サーバー間でAddnessの組織の情報を読むためのAPIです。読めるのは次の2つだけです。

• 組織のメンバーの一覧
• メンバー全員の今やるべきToDoと、そのToDoに関係するゴールの階層（日付を指定できます）

書き込み・通知・チャットなど、ほかの情報はこのキーでは読めません。

試験公開中です: このAPIは、Addnessが公開を決めた組織でだけ使えます。公開されていない組織では、APIキーを作る画面に「種類」の欄が出ず、連携用APIキーを作れません。すでにあるキーで呼んでも 403 EXTERNAL_INTEGRATION_FEATURE_DISABLED になります。公開を止めたときもキーは失効せず、再開すると同じキーで読めます。

MCP連携との違い

• 使うもの: 外部連携APIは自社のシステム（サーバー）。MCP連携はあなたが使うAIエージェント。
• 名義: 外部連携APIは組織に1つの連携（ボット）で、組織のメンバーにはなりません。MCP連携はログインしたあなた本人。
• できること: 外部連携APIはメンバーの一覧と今やるべきToDoを読むだけ。MCP連携はあなたの権限の範囲で、ゴールの読み書きなど。
• 認証: 外部連携APIは組織に固定のキー（Authorization: Bearer）。MCP連携はブラウザでのログイン（OAuth）。

AIからAddnessを使うときはMCP連携を使います。連携用APIキーは、MCPでもほかのAPIでも使えません（403 AUTH_API_KEY_RESOURCE_RESTRICTED）。

キーを用意する

1. 組織の管理者が、組織の設定 › 連携の「開発者向け」にある「APIキー」で「新規作成」を押し、「種類」で「連携用APIキー」を選びます。
2. 名前（100文字まで）とキーの有効期限を入れて、「作成する」を押します。有効期限は30日・90日・365日から選び、無期限は選べません。
3. キー（sk- で始まる文字列）は、作ったときに1回だけ表示されます。閉じると二度と表示できないので、その場で外部システムに設定してください。

連携用APIキーは組織に1つだけ作れます。作成済みの組織では「連携用APIキー」を選べず、「作成済みです。一覧から更新してください。」と表示されます。APIキーの一覧の「更新」でキーを入れ替えます。キーは作った組織だけで使えます。

• キーの更新: APIキーの一覧で、連携用APIキーの「更新」を押して新しいキーを発行します。古いキーには「入れ替え中」と期限が表示され、「今の期限」と「更新から7日後」の早い方まで並行して使えます。
• キーの失効: APIキーの一覧で失効したキーは、すぐに使えなくなります（401）。最後の1本を失効すると、新しく作るまで外部システムは読み取れません。
• 組織の削除: すべてのキーが使えなくなります。

呼び方

接続先は https://vt.api.addness.com です。すべての要求で、キーを Authorization ヘッダーに付けます。

curl -H "Authorization: Bearer sk-xxxxxxxx" \
  "https://vt.api.addness.com/api/v1/external/organizations/{組織ID}/members"

• {組織ID} には、キーを作った組織のIDを書きます。別の組織を指定すると 403 AUTH_API_KEY_ORG_MISMATCH です。
• X-Organization-ID ヘッダーは不要です。付けるなら同じ組織IDにします。
• 使えるのは次の2つの GET だけです。
  • メンバーの一覧: GET /api/v1/external/organizations/{組織ID}/members
  • 今やるべきToDo: GET /api/v1/external/organizations/{組織ID}/today-todos

メンバーの一覧

GET /api/v1/external/organizations/{組織ID}/members?limit=100&cursor=…

{
  "members": [
    {"memberId": "0b6f0e8e-…", "name": "山田 花子", "isGuest": false, "isExternal": false}
  ],
  "nextCursor": "MGI2ZjBl…"
}

• 並びは memberId の順です。
• 人のメンバーだけを返します。AIエージェントと、組織を抜けたメンバーは含みません。
• メールアドレス・ユーザーID・アバター・上司・タグは返しません。

今やるべきToDo

GET /api/v1/external/organizations/{組織ID}/today-todos?date=2026-10-05&limit=50&cursor=…

{
  "activityDate": "2026-10-05",
  "timezone": "Asia/Tokyo",
  "members": [
    {
      "memberId": "0b6f0e8e-…",
      "todos": [
        {"todoId": "7d1c2b0a-…", "kind": "goal", "objectiveId": "c3a0f4c2-…", "createdAt": "2026-10-04T23:30:00Z"}
      ],
      "goals": [
        {"id": "9f0a1b2c-…", "parentId": null, "orderNo": 1, "title": "第3四半期の目標", "status": "NONE", "completedAt": null, "isWaitingOnOther": false},
        {"id": "c3a0f4c2-…", "parentId": "9f0a1b2c-…", "orderNo": 2, "title": "週次の振り返りを書く", "status": "COMPLETED", "completedAt": "2026-10-05T02:10:00Z", "isWaitingOnOther": false}
      ]
    }
  ],
  "nextCursor": null
}

todos は「誰が何を今やるべきToDoに選んだか」、goals はそのゴールの件名・親子・状態です。ゴールの件名と状態は goals が正本で、todos の行は objectiveId だけを持ちます。

todos に入るのは、ゴールから入れた行（kind: "goal"）だけです。ゴールに紐づかない自由ToDo（Goalタスクを実行した行と、繰り返しの予定の実績も含みます）は返しません。

• メンバーの集合はメンバーの一覧と同じです。ToDoが無いメンバーも、空の todos・goals で返します。
• 1人の行の並びは、Addnessの画面と同じです（手動の並び順、次に入れた順）。1人あたりのToDoは最大800行です。

ゴールの階層（goals）

goals は、メンバーページの「今やるべきToDo」欄の木を作る材料です。

goals に入るのは、その日のToDoのゴールと、その子孫・祖先のうち画面の候補（本人の担当ゴールとその祖先、その日に完了したゴール、他担当の待ち行）に入るものだけです。組織のゴールの木全体は入りません。担当者・説明文・期限・数値は返しません。

goals を全部そのまま並べても「今やるべきToDo」欄にはなりません。画面と同じ木にするには、次の順で組み立てます。

1. todos の objectiveId を起点にします（同じゴールのToDoが複数あっても木の行は1つ）。起点は goals に必ずあります。画面の候補に入らないゴールは、parentId: null の根として goals の末尾にあります。組織の外か削除済みのゴールだけは goals に無いので、そのToDoは件名無しで扱います。
2. 起点から parentId を子の方向にたどり、goals の中の子孫を全部足します。
3. 起点ごとに直上の親を足します。別々の起点の枝が同じ祖先で合流するときは、その共通の祖先と、そこまでの間のゴールも足します。足した祖先は文脈の行（画面では灰色）です。goals に無い親は追わず、その子を根にします。
4. 兄弟は orderNo の昇順（同じ値は配列の順）で並べ、根から深さ優先で表示します。深さは組み立てた木で数え直します。
5. 完了した行も同じ位置に残します。isWaitingOnOther の行は、親の下に「待ち」として表示します。

ページを最後まで読む

どちらのAPIも、応答の nextCursor を次の要求の cursor に渡し、nextCursor が null になるまで読みます。

• ページは人数（limit）だけで切ります。ToDoの行数では切りません。
• cursor の中身には依存しないでください。読めない cursor は 400 INVALID_REQUEST です。

日付の決まり

• 日は組織のタイムゾーン（応答の timezone。設定が無ければ Asia/Tokyo）の午前4時で切り替わります。
• 今日（date を省略、または今日の日付）: 今の一覧です。未完了の行は、完了するか外すまで日をまたいで残ります。
• 過去の日: その日に入れた行と、その日に完了した行です。その日に画面に見えていた一覧とは、次の点で一致しません。
  • 前の日から持ち越して未完了のまま残っていた行と、あとで外した（削除した）行は出ません。
  • ゴールの件名・親・状態（goals）はその日に保存されたもので、今のゴールの状態では上書きしません。保存が無い日は goals が空です。
• 未来の日: 指定できません（400 INVALID_REQUEST）。
• 時刻（createdAt・completedAt）はすべてUTCです。

制限

• 超えると 429（1ページの時間切れは 504）を返します。コードは下の「エラー」を見てください。
• 拒否された要求も同じ枠を使います。
• 429・504 のときは、Retry-After（秒）のあとで再試行します。504 のときは limit を小さくします。
• 並列は2本以下にします。1巡の要求数は「人数÷limit（切り上げ）」ページ分で、limit を小さくすると1巡のページ数は増えます。
• 1時間の要求（1巡のページ数×巡回数）が120回に収まるよう、人数と limit に合わせて間隔を延ばします。たとえば limit を50にしたとき、120人なら1巡3回なので5分に1回程度（1時間36回）で収まります。600人なら1巡12回なので、5分に1回では1時間144回になって上限を超えます。6分より長い間隔にしてください。再試行も回数に入るので、余裕を持たせます。

エラー

エラーの本文は {"error": "理由", "code": "コード"} です。判定には code を使います。

400

• INVALID_REQUEST: limit が範囲外、cursor が読めない、date の形式が違う、未来の日
• AUTH_ORGANIZATION_ID_INVALID: path の組織IDがUUIDでない

401

• AUTH_INVALID_API_KEY など: キーが無い・無効・失効・期限切れ（連携や組織の削除を含む）

403

• AUTH_API_KEY_ORG_MISMATCH: 別の組織を指定した
• AUTH_API_KEY_RESOURCE_RESTRICTED: 連携用APIキーでないキーで呼んだ。または連携用APIキーでこの2本以外を呼んだ
• AUTH_EXTERNAL_INTEGRATION_KEY_REQUIRED: ログインのセッションで呼んだ
• EXTERNAL_INTEGRATION_FEATURE_DISABLED: 組織でこのAPIが公開されていない（キーは有効なまま）
• EXTERNAL_INTEGRATION_INACTIVE: 最後のキーの失効などで、連携が削除されている

429（Retry-After 秒のあとで再試行）

• API_KEY_RATE_LIMIT_EXCEEDED・RATE_LIMIT_EXCEEDED: キー・連携のレート制限を超えた
• EXTERNAL_READ_BUSY: 今やるべきToDoの同時数の上限に当たった
• EXTERNAL_GOALS_RATE_LIMITED: 今やるべきToDoの頻度の上限（組織ごとに120回/時）に当たった

504（Retry-After 秒のあとで、limit を小さくして再試行）

• EXTERNAL_READ_TIMEOUT: 今やるべきToDoの1ページが10秒に収まらなかった