API リファレンス

B-Beacon が提供する REST API およびエンドポイントの技術仕様です。自社サイトへの稼働状況埋め込みや独自のヘッドレス・ステータスページの構築、監視メトリクスの送信にご利用いただけます。

1. 公開ステータス取得 API（Headless Status API）

自社のWebサイト、フッター、管理画面内のヘルプバー、モバイルアプリ、あるいは自作の独自デザインのステータスページにリアルタイムのシステム稼働状況を組み込むための公開 JSON API です。

エンドポイント

※ {teamSlug} はステータスページのURL（例: /status/my-team）で使用しているチーム識別子です。

セキュリティ ＆ 更新間隔（負荷防御）仕様

外部の自社サイトやアプリからアクセスが集中しても安全に稼働し続けるよう、以下の防御策が組み込まれています：

• 60秒のサーバーサイドキャッシュ: サーバー側で結果が60秒間メモリ上にキャッシュされます。自社サイトに毎秒数万のアクセスがあっても、B-BeaconへのDB負荷は1分に1回のみに抑えられ、超高速（通常10ms以下）に応答します。
• レートリミット（60回 / 分 / IP）: 同一IPアドレスから1分間に60回を超える過剰なリクエストが行われた場合、HTTP 429 Too Many Requests を返します。
• 機密情報の完全遮断（ホワイトリスト方式）: 監視対象の内部URL、プライベートIP、ポート番号、Basic認証パスワード、非公開コンポーネント、内部エラーメッセージは一切出力されません。公開しても安全な項目のみが抽出されます。
• CORS（Cross-Origin Resource Sharing）対応: Access-Control-Allow-Origin: * ヘッダーが返されるため、ブラウザのJavaScriptから直接 fetch() して利用できます。
• HTTP キャッシュヘッダー: Cache-Control: public, max-age=30, s-maxage=60 が付与されており、ブラウザやエッジCDNでのキャッシュが推奨されます。

レスポンス例（JSON）

{
  "team": {
    "name": "Acme Corporation",
    "slug": "acme"
  },
  "overall_status": "operational",
  "overall_status_label": "すべてのシステムが正常稼働中",
  "overall_uptime_percentage": 99.98,
  "updated_at": "2026-10-09T10:00:00+09:00",
  "services": [
    {
      "name": "Web Platform",
      "slug": "web-platform",
      "description": "顧客向けWebポータルおよびAPI",
      "color": "#3B82F6",
      "uptime_percentage": 99.99,
      "components": [
        {
          "name": "API サーバー",
          "status": "operational",
          "status_label": "正常稼働中",
          "description": "REST API エンドポイント",
          "uptime_percentage": 100.0,
          "avg_response_time_ms": 118
        },
        {
          "name": "決済ゲートウェイ連携",
          "status": "operational",
          "status_label": "正常稼働中",
          "description": "Stripe決済処理システム",
          "uptime_percentage": 99.95,
          "avg_response_time_ms": 342
        }
      ]
    }
  ],
  "active_incidents": [],
  "upcoming_maintenances": []
}

主なステータス値一覧

実装コード例

1. JavaScript (Vanilla / ブラウザ fetch)

// 自社サイトのヘッダーやフッターで稼働状況を表示する例
async function checkSystemStatus() {
  try {
    const res = await fetch('https://getbbeacon.com/api/v1/status/acme');
    if (!res.ok) throw new Error('Status fetch failed');
    const data = await res.json();

    const indicator = document.getElementById('status-indicator');
    if (data.overall_status === 'operational') {
      indicator.innerHTML = '<span style="color: green;">● すべてのシステムが正常稼働中</span>';
    } else {
      indicator.innerHTML = `<span style="color: red;">▲ ${data.overall_status_label}</span>`;
    }
  } catch (err) {
    console.error('Failed to load status:', err);
  }
}

checkSystemStatus();

2. React / Next.js (コンポーネント例)

import { useEffect, useState } from 'react';

export function SystemStatusBadge() {
  const [status, setStatus] = useState(null);

  useEffect(() => {
    fetch('https://getbbeacon.com/api/v1/status/acme')
      .then(res => res.json())
      .then(data => setStatus(data))
      .catch(() => setStatus(null));
  }, []);

  if (!status) return null;

  const isUp = status.overall_status === 'operational';

  return (
    <a href="https://getbbeacon.com/status/acme" target="_blank" rel="noopener noreferrer"
       className="inline-flex items-center gap-2 px-3 py-1 rounded-full text-xs font-medium bg-slate-100 hover:bg-slate-200">
      <span className={`w-2 h-2 rounded-full ${isUp ? 'bg-emerald-500' : 'bg-rose-500'}`} />
      <span>{status.overall_status_label}</span>
      <span className="text-slate-400 font-mono">({status.overall_uptime_percentage}%)</span>
    </a>
  );
}

3. cURL コマンド

curl -s https://getbbeacon.com/api/v1/status/acme | jq .

2. Heartbeat 受信エンドポイント

Cron ジョブやバックグラウンドワーカーの死活監視を行うための Push 型 ping エンドポイントです。処理完了時にこの URL へ HTTP GET リクエストを送信してください。

使用例（シェルスクリプト / Cron）

# バックアップ実行後に Ping を送信（失敗時は送信されないためアラート発報）
0 * * * * /usr/local/bin/backup.sh && curl -fsS https://getbbeacon.com/api/heartbeat/YOUR_TOKEN > /dev/null

3. サーバー監視（Agent）メトリクス送信 API

サーバー監視モニター（Agent）へ、CPU、メモリ、ディスク使用率、ロードアベレージ等のメトリクスを直接送信するエンドポイントです。

リクエストボディ（JSON）

{
  "cpu_usage": 15.4,
  "memory_used_bytes": 4294967296,
  "memory_total_bytes": 17179869184,
  "disk_used_bytes": 53687091200,
  "disk_total_bytes": 268435456000,
  "load_avg_1m": 0.45,
  "process_count": 128
}