PCS API（開発者向け）

概要

PCS API は、PCS の bot・マイクラサーバーをプログラムから操作するための API です。電源の操作、状態・使用量・ログの取得、設定の変更、ファイルとバックアップの操作、操作の履歴の取得に対応しています。

対象は bot とマイクラサーバーです。PCS WEB のサイトと PCS VPS は対象外です。プレミアムの bot も、1個ずつ操作できます。

ご利用条件

PCS PASS 会員向けの機能です。PCS PASS の期間が終了すると API キーと Webhook は停止し、再びご加入いただくと同じ設定のままご利用いただけます。

共通仕様

ベース URL	`https://pcs-cloud.jp/api/v1`
認証	`Authorization` ヘッダーに API キーを指定します（認証と API キー）。
リクエスト	本文は JSON（UTF-8・`Content-Type: application/json`）で送信します。フォーム形式の本文にも対応しています。
レスポンス	JSON（UTF-8）で返します。ファイルのダウンロードのみ、ファイルの内容をそのまま返します。
日時	ISO 8601 形式・日本時間で返します（例: `2026-10-02T14:03:12+09:00`）。
サーバー ID	パスの `{id}` には、`GET /servers` で取得できる `id` を指定します。管理画面の URL（https://pcs-cloud.jp/core/1482 の 1482）でも確認できます。
エラー	`{"error": "…", "code": "…"}` の形式で返します（エラー）。

プログラムでの判定には code を使用してください。error の文言は変更することがあります。

JSON

{
  "error": "この API キーには「電源の操作」の権限がありません。必要な権限を付与した API キーをアカウント設定で発行してください。",
  "code": "insufficient_scope",
  "required": "power"
}

HTTP ステータス

ステータス	内容
200	成功
202	受け付け（バックアップの作成・復元。処理は受け付けた後に実行します）
401	API キーの指定なし・無効な API キー
402	ウォレットの残高不足（時間制のサーバーの起動時）
403	権限の不足、サーバーのご利用停止、契約期間の終了など
404	URL・サーバー・ファイルが見つからない
405	対応していない HTTP メソッド
409	サーバーの準備中・バックアップの処理中・同じ名前のファイルやフォルダがある場合
413	サイズ・フォルダ内の項目数の上限の超過
422	パラメーターの誤り
429	回数・転送量の上限
500・502・503	PCS 側のエラー・メンテナンス・混雑

認証と API キー

すべてのリクエストで、Authorization ヘッダーに API キーを指定します。API キーは pcs_ で始まる文字列です。

HTTP

Authorization: Bearer pcs_…

発行	アカウント設定の「PCS API・Webhook」で発行します。
発行できる数	1つのアカウントで同時に5個まで
表示	API キーは、発行した画面でのみ表示されます。
お知らせ	API キーの発行・無効化の際は、登録メールアドレスへお知らせします。
無効化	不要になったキーや、漏えいのおそれがあるキーは、アカウント設定で無効化してください。無効化したキーは直ちに使用できなくなります。

権限

API キーごとに、使用できる操作（権限）を選んで発行します。閲覧の権限は、すべてのキーに付与されます。

権限	code	対象の操作
閲覧	`read`	サーバーの一覧・詳細、使用量、ログ、バックアップの一覧、操作の履歴、アカウントの情報の取得
電源の操作	`power`	起動・停止・再起動・強制停止
設定の変更	`settings`	サーバー名・起動ファイル・死活監視・自動再起動の変更
ファイルの読み込み	`files.read`	ファイルの一覧・内容の取得、ダウンロード
ファイルの書き込み	`files.write`	ファイルの書き込み・アップロード・削除、フォルダの作成、名前の変更
バックアップ	`backups`	バックアップの作成・復元

用途ごとに、必要な権限だけを付与した API キーを発行することを推奨します。PCS API の提供開始前に発行した API キー（ck_ で始まるキーなど）は、従来のキーとして、閲覧（ログ・操作の履歴を除く）と電源の操作に引き続きご利用いただけます。ログと操作の履歴を取得する場合は、権限を選んで API キーを新たに発行してください。

閲覧専用のキー

状態の確認だけに使う API キーは、発行時に権限のチェックをすべて外して発行します。閲覧の権限だけを持つキーとなり、電源の操作やファイルの変更には使用できません。閲覧の権限では、コンソールのログと操作の履歴も取得できます。API キーは、Web ページなど第三者が見られる場所には記載しないでください。

クイックスタート

Python（requests）

API キーの発行

アカウント設定の「PCS API・Webhook」で、キーの名前と権限を選んで発行します。

アカウント設定 →

キーの確認

GET /me を呼び出し、キーの名前と権限が返ることを確認します。

サーバーの操作

GET /servers でサーバー ID を確認し、電源の操作などを行います。

次の例は、キーを確認してサーバーの一覧を表示し、PCS_SERVER_ID で指定したサーバーを再起動します。PCS_SERVER_ID を指定していない場合は、一覧を表示して終了します。

.env

PCS_API_KEY=pcs_…
PCS_SERVER_ID=1482

Python

import os
import sys

import requests

API = "https://pcs-cloud.jp/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PCS_API_KEY']}"}


def call(method, path, **kwargs):
    r = requests.request(method, f"{API}{path}", headers=HEADERS, timeout=30, **kwargs)
    try:
        body = r.json()
    except ValueError:
        sys.exit(f"HTTP {r.status_code}")
    if not r.ok:
        sys.exit(f"{body.get('code')}: {body.get('error')}")
    return body


# キーの確認（キーの名前と権限）
me = call("GET", "/me")
print(me["key"]["name"], me["key"]["abilities"])

# サーバーの一覧
for s in call("GET", "/servers")["servers"]:
    print(s["id"], s["name"], s["type"], s["state"])

# PCS_SERVER_ID で指定したサーバーを再起動する（指定がない場合は一覧の表示だけで終了）
server_id = os.environ.get("PCS_SERVER_ID")
if not server_id:
    sys.exit("再起動するサーバーの ID を PCS_SERVER_ID に指定してください。")
call("POST", f"/servers/{server_id}/power", json={"action": "restart"})
print("再起動を受け付けました。")

停止しているサーバーを再起動すると、サーバーが起動します。時間制のマイクラサーバーは、起動している間の料金がウォレットから差し引かれます。

PCS のサーバーで動かす場合は、API キーとサーバー ID をサーバーの .env に PCS_API_KEY=… と PCS_SERVER_ID=… の形式で保存し、os.environ から読み込んでください。コードに直接書かないでください。

discord.py から操作する

discord.py 2.x・aiohttp

Discord のスラッシュコマンド /restart で、PCS のサーバーを再起動する例です。コマンドは、サーバーの管理者だけが使用できるように登録します。

API キーは、閲覧と電源の操作の権限だけを付与したものをご利用ください。API キーは、サーバーの .env に PCS_API_KEY=… の形式で保存し、os.environ から読み込んでください。コードに直接書かないでください。

.env

PCS_API_KEY=pcs_…
PCS_SERVER_ID=1482

Python

import asyncio
import os

import aiohttp
import discord
from discord import app_commands

API = "https://pcs-cloud.jp/api/v1"
API_KEY = os.environ["PCS_API_KEY"]      # 閲覧と電源の操作の権限だけを付与した API キー
SERVER_ID = os.environ["PCS_SERVER_ID"]  # 操作するサーバーの ID（GET /servers の id）


class Bot(discord.Client):
    def __init__(self) -> None:
        super().__init__(intents=discord.Intents.default())
        self.tree = app_commands.CommandTree(self)
        self.pcs: aiohttp.ClientSession | None = None

    async def setup_hook(self) -> None:
        # PCS API との通信に使うセッションは1つだけ作り、使い回す
        self.pcs = aiohttp.ClientSession(headers={"Authorization": f"Bearer {API_KEY}"})
        await self.tree.sync()

    async def close(self) -> None:
        if self.pcs is not None:
            await self.pcs.close()
        await super().close()


bot = Bot()


@bot.tree.command(name="restart", description="PCS のサーバーを再起動します")
@app_commands.default_permissions(administrator=True)
@app_commands.guild_only()
async def restart(interaction: discord.Interaction) -> None:
    await interaction.response.defer(ephemeral=True, thinking=True)

    try:
        async with bot.pcs.post(
            f"{API}/servers/{SERVER_ID}/power",
            json={"action": "restart"},
            timeout=aiohttp.ClientTimeout(total=30),
        ) as resp:
            data = await resp.json(content_type=None)
    except (aiohttp.ClientError, asyncio.TimeoutError, ValueError):
        await interaction.followup.send("再起動できませんでした（network_error）。", ephemeral=True)
        return

    if resp.status == 200:
        await interaction.followup.send("再起動を受け付けました。", ephemeral=True)
    elif resp.status == 429:
        wait = data.get("retry_after", 60)
        await interaction.followup.send(
            f"再起動できませんでした（rate_limited）。{wait}秒後に再度お試しください。", ephemeral=True
        )
    else:
        await interaction.followup.send(f"再起動できませんでした（{data.get('code')}）。", ephemeral=True)


bot.run(os.environ["DISCORD_TOKEN"])

電源の操作は完了までに数秒かかることがあるため、最初に defer で応答を保留し、結果は followup で送信します。
bot 自身を再起動した場合、応答を送る前に bot が停止することがあります。

エンドポイント一覧

ベース URL https://pcs-cloud.jp/api/v1

メソッド・パス	内容	必要な権限
GET`/servers`	サーバーの一覧の取得	必要な権限閲覧
GET`/servers/{id}`	サーバーの詳細の取得	必要な権限閲覧
POST`/servers/{id}/power`	電源の操作	必要な権限電源の操作
GET`/servers/{id}/resources`	使用量の取得	必要な権限閲覧
GET`/servers/{id}/logs`	ログの取得	必要な権限閲覧
PATCH`/servers/{id}`	設定の変更	必要な権限設定の変更
GET`/servers/{id}/files`	ファイルの一覧の取得	必要な権限ファイルの読み込み
GET`/servers/{id}/files/content`	ファイルの内容の取得	必要な権限ファイルの読み込み
GET`/servers/{id}/files/download`	ファイルのダウンロード	必要な権限ファイルの読み込み
POST`/servers/{id}/files/write`	ファイルの書き込み	必要な権限ファイルの書き込み
POST`/servers/{id}/files/upload`	ファイルのアップロード	必要な権限ファイルの書き込み
POST`/servers/{id}/files/delete`	ファイルの削除	必要な権限ファイルの書き込み
POST`/servers/{id}/files/mkdir`	フォルダの作成	必要な権限ファイルの書き込み
POST`/servers/{id}/files/rename`	名前の変更	必要な権限ファイルの書き込み
GET`/servers/{id}/backups`	バックアップの一覧の取得	必要な権限閲覧
POST`/servers/{id}/backups`	バックアップの作成	必要な権限バックアップ
POST`/servers/{id}/backups/restore`	バックアップの復元	必要な権限バックアップ
GET`/history`	操作の履歴の取得	必要な権限閲覧
GET`/me`	アカウントと API キーの情報の取得	必要な権限閲覧

サーバー

契約中の bot・マイクラサーバーの一覧と詳細を取得できます。プレミアムの bot も1個ずつ含まれます（parent_id に契約元のサーバーの ID が入ります）。解約済みのサーバーと PCS WEB のサイトは含まれません。

サーバーの一覧の取得

GET /servers

必要な権限閲覧 read

契約中のサーバーを返します。一覧の state は、死活監視で最後に確認した状態です。

パラメーター

パラメーターはありません。

リクエストの例

curl

curl -sS https://pcs-cloud.jp/api/v1/servers \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "servers": [
    {
      "id": 2051,
      "name": "survival",
      "type": "minecraft",
      "plan": "mc4",
      "plan_label": "マイクラ 4GB",
      "parent_id": null,
      "status": "active",
      "status_reason": null,
      "state": "running",
      "state_checked_at": "2026-10-02T14:02:05+09:00",
      "billing": "hourly",
      "active_until": null,
      "auto_renew": false,
      "monitoring": true,
      "auto_restart": false,
      "stopped_by_user": false,
      "memory_mb": 4096,
      "disk_mb": 20480,
      "cpu_percent_limit": 300,
      "start_file": null,
      "connect": "203.0.113.10:25601",
      "badge_url": "https://pcs-cloud.jp/badge/core/8b1e4d27-5c3a-4f90-a6d2-19e7c0b3f5a8.svg"
    }
  ]
}

主なエラー

maintenance

サーバーの詳細の取得

GET /servers/{id}

必要な権限閲覧 read

指定したサーバーの情報を返します。詳細の state は、現在の状態です。

パラメーター

名前	型	必須	説明
include	stringクエリ	任意	`start_file` を指定すると、起動ファイル（bot のみ）を含めて返します。

リクエストの例

curl

curl -sS "https://pcs-cloud.jp/api/v1/servers/1482?include=start_file" \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "server": {
    "id": 1482,
    "name": "music-bot",
    "type": "bot",
    "plan": "standard",
    "plan_label": "スタンダード",
    "parent_id": null,
    "status": "active",
    "status_reason": null,
    "state": "running",
    "state_checked_at": "2026-10-02T14:02:05+09:00",
    "billing": "monthly",
    "active_until": "2026-10-29T18:42:10+09:00",
    "auto_renew": true,
    "monitoring": true,
    "auto_restart": true,
    "stopped_by_user": false,
    "memory_mb": 1536,
    "disk_mb": 30720,
    "cpu_percent_limit": 180,
    "start_file": "main.py",
    "connect": null,
    "badge_url": "https://pcs-cloud.jp/badge/core/3f2c9a1e-7b4d-4c1a-9e52-8d0f6a2b71c4.svg"
  }
}

主なエラー

not_found maintenance upstream_busy

フィールド

名前	型	内容
id	integer	サーバー ID
name	string	サーバー名
type	string	`bot` または `minecraft`
plan	string	プランのコード（例: `standard`、`mc4`）
plan_label	string	プラン名（例: スタンダード）
parent_id	integer \| null	プレミアムの bot の場合、契約元のサーバーの ID
status	string	契約の状態（下の表）
status_reason	string \| null	ご利用を停止している理由（下の表）。停止していない場合は `null`
state	string \| null	稼働状態（下の表）
state_checked_at	string \| null	死活監視で状態を確認した日時
billing	string	`monthly`（月額）または `hourly`（時間制）
active_until	string \| null	契約期間の終了日時。時間制のサーバーとプレミアムの bot は `null`（プレミアムの bot は、契約元のサーバーの値をご確認ください）
auto_renew	boolean	自動更新の設定
monitoring	boolean	死活監視の設定
auto_restart	boolean	自動再起動の設定
stopped_by_user	boolean	マイページ・Discord・API からの停止、バックアップの復元、残高の不足による停止などで停止し、まだ起動していない場合は `true`。この間は自動再起動を行いません
memory_mb	integer	メモリの上限（MB）
disk_mb	integer	ディスクの上限（MB）
cpu_percent_limit	integer	CPU の上限（1コア分を 100 とした値）
start_file	string \| null	起動ファイル。詳細で `include=start_file` を指定した場合のみ（bot のみ）
connect	string \| null	接続先のアドレスとポート（マイクラサーバーのみ）
badge_url	string \| null	稼働バッジの URL
children	array	プレミアムの契約元のサーバーの詳細のみ。bot のサーバー ID の一覧

値の一覧

state	稼働状態
running	稼働中
offline	停止
starting	起動中
stopping	停止処理中
null	未確認

status	契約の状態
active	ご利用中
suspended	ご利用停止中
pending	準備中
cancelled	解約済み

status_reason	停止の理由
expired	契約期間の終了
balance	残高の不足
abuse	利用規約に基づく措置
phone	電話番号の確認が未完了
admin	運営による停止
parent	契約元のサーバーのご利用停止

一覧の state は、死活監視で最後に確認した状態です。現在の状態は GET /servers/{id} で取得してください。

電源の操作

サーバーの起動・停止・再起動・強制停止を行います。応答は、操作を受け付けたことを示します。起動の完了は GET /servers/{id} の state でご確認ください。

電源の操作

POST /servers/{id}/power

必要な権限電源の操作 power

パラメーター

名前	型	必須	説明
action	string本文	必須	`start`・`stop`・`restart`・`kill` のいずれか（下の表）

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/1482/power \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"restart"}'

レスポンスの例（200）

JSON

{
  "ok": true,
  "action": "restart"
}

主なエラー

insufficient_scope suspended expired pending busy balance_short maintenance rate_limited

action	操作	内容
start	起動	停止しているサーバーを起動します。
stop	停止	サーバーを停止します。
restart	再起動	サーバーを停止してから起動します。
kill	強制停止	終了処理を待たずに停止します。保存されていないデータは失われることがあります。

時間制のマイクラサーバー

時間制のマイクラサーバーは、起動している間の料金がウォレットから差し引かれます。起動・再起動には、ウォレットに所定の残高が必要です。残高が不足している場合は 402 balance_short を返し、必要な金額を required_yen に含めます。

マイページ・Discord・API から停止したサーバーは、再び起動するまで自動再起動を行いません。
自動再起動は、時間制のサーバーには適用されません。
契約期間が終了したサーバーは、起動・再起動できません。停止・強制停止は行えます。
バックアップの復元中は、起動・再起動できません（409 busy）。起動は、復元の完了（バックアップの一覧の job の status が done）を確認してから行ってください。

使用量とログ

指定したサーバーの CPU・メモリ・ディスク・通信量の現在の値と、コンソールの出力を取得できます。

使用量の取得

GET /servers/{id}/resources

必要な権限閲覧 read

サーバーの現在の使用量を返します。容量の単位はバイトです。

パラメーター

パラメーターはありません。

リクエストの例

curl

curl -sS https://pcs-cloud.jp/api/v1/servers/1482/resources \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "state": "running",
  "cpu_percent": 12.4,
  "cpu_percent_limit": 180,
  "memory_bytes": 94371840,
  "memory_limit_bytes": 1610612736,
  "disk_bytes": 52428800,
  "disk_limit_bytes": 32212254720,
  "network_rx_bytes": 18350080,
  "network_tx_bytes": 6291456,
  "uptime_seconds": 86400
}

主なエラー

not_found pending upstream_unavailable upstream_busy

名前	内容
state	稼働状態（サーバーの値の一覧と同じ）
cpu_percent	CPU の使用率（1コア分を 100 とした値）
cpu_percent_limit	CPU の上限
memory_bytes memory_limit_bytes	メモリの使用量と上限
disk_bytes disk_limit_bytes	ディスクの使用量と上限
network_rx_bytes network_tx_bytes	起動してからの受信量と送信量
uptime_seconds	起動してからの秒数。停止中は `null`

ログの取得

GET /servers/{id}/logs

必要な権限閲覧 read

コンソールの出力の直近の行を、古い順に返します。文字の色などの制御文字は取り除いて返します。従来の API キーでは取得できません（insufficient_scope）。

パラメーター

名前	型	必須	説明
lines	integerクエリ	任意	取得する行数（1〜100）。既定は100

リクエストの例

curl

curl -sS "https://pcs-cloud.jp/api/v1/servers/1482/logs?lines=3" \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "lines": [
    "2026-10-02 14:03:05 INFO     discord.client logging in using static token",
    "2026-10-02 14:03:06 INFO     discord.gateway Shard ID None has connected to Gateway",
    "music-bot としてログインしました"
  ]
}

主なエラー

insufficient_scope not_found pending validation upstream_unavailable

設定の変更

サーバー名・起動ファイル・死活監視・自動再起動を変更できます。指定した項目だけを変更し、変更後のサーバーの情報を返します。

設定の変更

PATCH /servers/{id}

必要な権限設定の変更 settings

1つ以上の項目を指定してください。指定がない場合は no_fields を返します。

パラメーター

名前	型	必須	説明
name	string本文	任意	サーバー名（40文字以内）。英数字・日本語・`-`・`_`・`.`・空白を使用できます
start_file	string本文	任意	起動ファイルのパス。先頭の `/` を付けずに指定します（例: `main.py`、`bot/main.py`）。bot のみ
monitoring	boolean本文	任意	死活監視の ON・OFF
auto_restart	boolean本文	任意	自動再起動の ON・OFF

リクエストの例

curl

curl -sS -X PATCH https://pcs-cloud.jp/api/v1/servers/1482 \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_file":"bot/main.py","auto_restart":true}'

レスポンスの例（200）

JSON

{
  "server": {
    "id": 1482,
    "name": "music-bot",
    "type": "bot",
    "plan": "standard",
    "plan_label": "スタンダード",
    "parent_id": null,
    "status": "active",
    "status_reason": null,
    "state": "running",
    "state_checked_at": "2026-10-02T14:02:05+09:00",
    "billing": "monthly",
    "active_until": "2026-10-29T18:42:10+09:00",
    "auto_renew": true,
    "monitoring": true,
    "auto_restart": true,
    "stopped_by_user": false,
    "memory_mb": 1536,
    "disk_mb": 30720,
    "cpu_percent_limit": 180,
    "start_file": "bot/main.py",
    "connect": null,
    "badge_url": "https://pcs-cloud.jp/badge/core/3f2c9a1e-7b4d-4c1a-9e52-8d0f6a2b71c4.svg"
  },
  "note": "起動ファイルの変更は、次回の起動から反映されます。"
}

主なエラー

validation no_fields start_file_not_found start_file_not_supported proxy_mode suspended expired pending

start_file には、サーバー内にある .py のファイルを指定します。変更は次回の起動から反映されます。マイクラサーバーと、プロキシモードを使用中のサーバーでは変更できません。
死活監視と自動再起動は PCS PASS の特典です。自動再起動は、時間制のサーバーには適用されません。

ファイル

サーバー内のファイルの一覧・読み込み・書き込み・アップロード・削除、フォルダの作成、名前の変更に対応しています。ご利用中（status が active）のサーバーが対象です。

パスの指定	サーバー内のパスを `/` から始めて指定します（例: `/main.py`、`/cogs/music.py`）。`..` を含むパス、制御文字・バックスラッシュを含むパス、512バイトを超えるパスは指定できません。
シンボリックリンク	操作できません。
テキスト	内容の取得・書き込みは 1 MB まで
アップロード・ダウンロード	1ファイル 25 MB まで。大きなファイルのアップロードは、完了まで1分ほどかかることがあります。大きなファイルのアップロードで 502 `upstream_error` が返った場合は、再度お試しください。
転送量	内容の取得・書き込み・アップロード・ダウンロードの合計で、1日 2 GB まで（日本時間の0時に戻ります）
フォルダ	書き込み・アップロードの際、存在しないフォルダは自動で作成します。項目（ファイル・フォルダ）が多すぎるフォルダ（目安として約3万5千項目を超えるもの）は、一覧の取得を含めて操作できません（413 `too_many_entries`）。
バックアップの復元中	ファイルの書き込み・アップロード・削除、フォルダの作成、名前の変更はできません（409 `busy`）。一覧・内容の取得・ダウンロードはできます。
記録	ファイルの読み込み・ダウンロードと、すべての変更を操作の履歴に記録します（ファイルの内容は記録しません）。

ファイルの一覧の取得

GET /servers/{id}/files

必要な権限ファイルの読み込み files.read

指定したフォルダの中身を、フォルダを先に、名前の順に返します。

パラメーター

名前	型	必須	説明
path	stringクエリ	任意	フォルダのパス。既定は `/`

リクエストの例

curl

curl -sS "https://pcs-cloud.jp/api/v1/servers/1482/files?path=/" \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "path": "/",
  "files": [
    { "name": "cogs", "size": 4096, "is_file": false, "modified": "2026-10-01T22:14:08+09:00" },
    { "name": ".env", "size": 118, "is_file": true, "modified": "2026-09-28T10:02:41+09:00" },
    { "name": "main.py", "size": 3481, "is_file": true, "modified": "2026-10-01T22:14:08+09:00" },
    { "name": "requirements.txt", "size": 34, "is_file": true, "modified": "2026-09-28T10:02:41+09:00" }
  ]
}

主なエラー

invalid_path not_found too_many_entries pending upstream_error unavailable

ファイルの内容の取得

GET /servers/{id}/files/content

必要な権限ファイルの読み込み files.read

テキストファイル（UTF-8）の内容を返します。1 MB を超えるファイルと、バイナリファイル（UTF-8 として読み込めないファイルを含む）は、/files/download をご利用ください。

パラメーター

名前	型	必須	説明
path	stringクエリ	必須	ファイルのパス

リクエストの例

curl

curl -sS "https://pcs-cloud.jp/api/v1/servers/1482/files/content?path=/requirements.txt" \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "path": "/requirements.txt",
  "content": "discord.py==2.4.0\naiohttp==3.10.5\n"
}

主なエラー

invalid_path not_found not_a_file symlink binary_file file_too_large transfer_limit

ファイルのダウンロード

GET /servers/{id}/files/download

必要な権限ファイルの読み込み files.read

ファイルの内容をそのまま返します。バイナリファイルにも対応しています。

パラメーター

名前	型	必須	説明
path	stringクエリ	必須	ファイルのパス

リクエストの例

curl

curl -sS -o users.db "https://pcs-cloud.jp/api/v1/servers/1482/files/download?path=/data/users.db" \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例

ファイルの内容を Content-Type: application/octet-stream で返します（1ファイル 25 MB まで）。

主なエラー

invalid_path root_not_allowed not_found not_a_file symlink too_large transfer_limit

ファイルの書き込み

POST /servers/{id}/files/write

必要な権限ファイルの書き込み files.write

テキストファイルを書き込みます。同じ名前のファイルがある場合は上書きします。

パラメーター

名前	型	必須	説明
path	string本文	必須	書き込むファイルのパス
content	string本文	必須	ファイルの内容（1 MB まで）。前後の空白や改行も、送信した内容のまま保存します。空の文字列も指定できます

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/1482/files/write \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/requirements.txt","content":"discord.py==2.4.0\naiohttp==3.10.5\n"}'

レスポンスの例（200）

JSON

{
  "ok": true,
  "path": "/requirements.txt"
}

主なエラー

invalid_path root_not_allowed symlink not_a_file validation busy too_many_entries transfer_limit upstream_error

ファイルのアップロード

POST /servers/{id}/files/upload

必要な権限ファイルの書き込み files.write

ファイルをアップロードします（multipart/form-data）。同じ名前のファイルがある場合は上書きします。

パラメーター

名前	型	必須	説明
file	fileフォーム	必須	アップロードするファイル（25 MB まで。超える場合は `validation` を返します）
dir	stringフォーム	任意	保存先のフォルダ。既定は `/`

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/1482/files/upload \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -F "file=@cogs/music.py" \
  -F "dir=/cogs"

レスポンスの例（200）

JSON

{
  "ok": true,
  "path": "/cogs/music.py"
}

主なエラー

invalid_path invalid_filename validation symlink not_a_file busy too_many_entries transfer_limit upstream_error

ファイルの削除

POST /servers/{id}/files/delete

必要な権限ファイルの書き込み files.write

ファイルとフォルダを削除します。フォルダは中身ごと削除します。削除したファイルは元に戻せません。指定したパスが1件でも見つからない場合は、何も削除せずに not_found を返します。1回で削除できるのは、10か所までのフォルダにあるファイル・フォルダです（確認のため、フォルダごとにサーバーへ問い合わせ、その回数を「サーバーに接続する操作の合計」に数えます）。

パラメーター

名前	型	必須	説明
paths	array本文	必須	削除するファイル・フォルダのパス（1〜100件。親フォルダは10か所まで）。`/` は指定できません

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/1482/files/delete \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paths":["/old_main.py","/logs"]}'

レスポンスの例（200）

JSON

{
  "ok": true
}

主なエラー

invalid_path root_not_allowed not_found symlink validation busy rate_limited upstream_error

フォルダの作成

POST /servers/{id}/files/mkdir

必要な権限ファイルの書き込み files.write

フォルダを作成します。途中のフォルダも作成します。すでに存在する場合は、"existed": true を含めて返します。同じ名前のファイルがある場合は already_exists を返します。

パラメーター

名前	型	必須	説明
path	string本文	必須	作成するフォルダのパス

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/1482/files/mkdir \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/cogs"}'

レスポンスの例（200）

JSON

{
  "ok": true
}

主なエラー

invalid_path root_not_allowed already_exists symlink busy too_many_entries upstream_error

名前の変更

POST /servers/{id}/files/rename

必要な権限ファイルの書き込み files.write

ファイル・フォルダの名前を変更します。変更後のパスに同じ名前のファイル・フォルダがある場合は、上書きせずに already_exists を返します。

パラメーター

名前	型	必須	説明
from	string本文	必須	変更前のパス
to	string本文	必須	変更後のパス

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/1482/files/rename \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"/main.py","to":"/bot.py"}'

レスポンスの例（200）

JSON

{
  "ok": true
}

主なエラー

invalid_path root_not_allowed not_found already_exists symlink busy too_many_entries upstream_error

GitHub Actions からの反映

リポジトリの main ブランチへの push のたびに、Python のファイルと requirements.txt をサーバーへアップロードし、サーバーを再起動する例です。

この例では、ファイルの書き込みと電源の操作の権限だけを付与した API キーを、リポジトリの Secrets に PCS_API_KEY として登録します。サーバー ID は、リポジトリの Variables に PCS_SERVER_ID として登録します。

サーバー ID は、GET /servers の id、または管理画面の URL（https://pcs-cloud.jp/core/1482 の 1482）で確認できます。

YAML

# .github/workflows/deploy.yml
name: Deploy to PCS

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Upload files and restart
        env:
          PCS_API_KEY: ${{ secrets.PCS_API_KEY }}
          PCS_SERVER_ID: ${{ vars.PCS_SERVER_ID }}
        run: |
          API="https://pcs-cloud.jp/api/v1/servers/$PCS_SERVER_ID"

          git ls-files '*.py' requirements.txt | while read -r f; do
            d=$(dirname "$f")
            if [ "$d" = "." ]; then d=""; fi
            curl -sS --fail-with-body --retry 5 \
              -H "Authorization: Bearer $PCS_API_KEY" \
              -F "file=@$f" \
              -F "dir=/$d" \
              "$API/files/upload"
          done

          curl -sS --fail-with-body --retry 5 \
            -H "Authorization: Bearer $PCS_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"action":"restart"}' \
            "$API/power"

ファイルの数が多い場合は、ファイルの書き込みの回数の上限（1分間に30回）に達することがあります。--retry を指定した curl は、429 の応答の Retry-After に従って再送します。リポジトリから削除したファイルは、サーバーからは削除されません。

バックアップ

バックアップは、サーバーのファイル一式を backup-日時.tar.gz としてサーバー内に保存します（ディスク容量を使用します）。作成のたびに最新3個までを保持し、古いものから削除します。マイクラサーバーは、毎日の自動バックアップの際に、自動バックアップを含めて最新2個までに整理します。

復元について

復元すると、バックアップに含まれるファイルで上書きします。バックアップの作成後に追加したファイルは削除されません。復元の前にサーバーを停止し、復元後も停止したままになります。

ファイル管理の圧縮などでサーバー直下に作られた archive-*.tar.gz も一覧に表示され、復元に指定できます（自動では削除しません）。

作成・復元は受け付けた後に実行し、完了まで数分かかることがあります。結果は GET /servers/{id}/backups の job、または GET /history でご確認ください。処理中のサーバーへの作成・復元は 409 busy を返します。作成・復元は、1つのアカウントで同時に1件まで実行できます（ほかのサーバーで処理中の場合も 409 busy）。

復元の処理中は、サーバーの起動・再起動とファイルの変更はできません（409 busy）。サーバーの起動は、job の status が done になってから行ってください。

バックアップの一覧の取得

GET /servers/{id}/backups

必要な権限閲覧 read

サーバー直下のバックアップ（backup-*.tar.gz）を新しい順に返し、その後にファイル管理の圧縮などで作られた archive-*.tar.gz を新しい順に返します。job には、API で最後に受け付けた作成・復元の状況が入ります（受け付けがない場合と、終了から1日を過ぎた場合は null）。

パラメーター

パラメーターはありません。

リクエストの例

curl

curl -sS https://pcs-cloud.jp/api/v1/servers/2051/backups \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "backups": [
    { "name": "backup-2026-10-02-140312.tar.gz", "size": 184549376, "modified": "2026-10-02T14:04:51+09:00" },
    { "name": "backup-2026-10-02-040000.tar.gz", "size": 183500800, "modified": "2026-10-02T04:01:37+09:00" }
  ],
  "job": {
    "action": "create",
    "status": "done",
    "file": "backup-2026-10-02-140312.tar.gz",
    "error": null,
    "code": null,
    "queued_at": "2026-10-02T14:03:12+09:00",
    "finished_at": "2026-10-02T14:04:52+09:00"
  }
}

主なエラー

not_found pending upstream_error unavailable

job の項目	内容
action	`create`（作成）または `restore`（復元）
status	`queued`（受付済み）・`running`（処理中）・`done`（完了）・`failed`（失敗）
file	作成・復元したバックアップのファイル名
error	失敗した場合の理由。それ以外は `null`
code	失敗した場合の code（処理が時間内に終わらなかった場合は `timeout`。サーバーで処理が続いている場合があるため、しばらくしてからバックアップの一覧をご確認ください）。それ以外は `null`
queued_at	受け付けた日時
finished_at	完了・失敗した日時。処理中は `null`

バックアップの作成

POST /servers/{id}/backups

必要な権限バックアップ backups

バックアップの作成を受け付けます。作成の完了は、バックアップの一覧の job でご確認ください。

パラメーター

パラメーターはありません。

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/2051/backups \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（202）

JSON

{
  "ok": true,
  "status": "queued"
}

主なエラー

busy suspended expired pending rate_limited unavailable

バックアップの復元

POST /servers/{id}/backups/restore

必要な権限バックアップ backups

バックアップからの復元を受け付けます。復元の前にサーバーを停止し、復元後も停止したままになります。

パラメーター

名前	型	必須	説明
file	string本文	必須	復元するバックアップのファイル名（バックアップの一覧の `name`）

リクエストの例

curl

curl -sS -X POST https://pcs-cloud.jp/api/v1/servers/2051/backups/restore \
  -H "Authorization: Bearer $PCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file":"backup-2026-10-02-040000.tar.gz"}'

レスポンスの例（202）

JSON

{
  "ok": true,
  "status": "queued"
}

主なエラー

validation not_found busy suspended expired unavailable

操作の履歴

API による操作の記録を、新しい順に取得できます。電源の操作、設定の変更、ファイルの読み込み・ダウンロードと変更、バックアップの作成・復元、API キーの発行・無効化を記録します。ファイルの内容は記録しません。

アカウント設定の「API の操作履歴」には、直近の10件を表示します。すべての履歴は、API の利用状況のページで確認できます。

操作の履歴の取得

GET /history

必要な権限閲覧 read

label は操作の日本語名、status は応答の HTTP ステータスです。バックアップの作成・復元は受け付けた時点の 202 で記録し、完了後に detail へ結果を追記します。従来の API キーでは取得できません（insufficient_scope）。

パラメーター

名前	型	必須	説明
limit	integerクエリ	任意	取得する件数（1〜100）。既定は50

リクエストの例

curl

curl -sS "https://pcs-cloud.jp/api/v1/history?limit=2" \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "history": [
    {
      "at": "2026-10-02T14:03:12+09:00",
      "key": { "name": "GitHub Actions", "prefix": "pcs_3f9a1c2b…" },
      "server": { "id": 1482, "name": "music-bot" },
      "action": "power.restart",
      "label": "再起動",
      "detail": null,
      "status": 200
    },
    {
      "at": "2026-10-02T14:03:09+09:00",
      "key": { "name": "GitHub Actions", "prefix": "pcs_3f9a1c2b…" },
      "server": { "id": 1482, "name": "music-bot" },
      "action": "files.upload",
      "label": "ファイルのアップロード",
      "detail": "/cogs/music.py",
      "status": 200
    }
  ]
}

主なエラー

insufficient_scope validation

action	操作
power.start	起動
power.stop	停止
power.restart	再起動
power.kill	強制停止
settings	設定の変更
files.read	ファイルの読み込み
files.download	ファイルのダウンロード
files.write	ファイルの書き込み
files.upload	ファイルのアップロード
files.delete	ファイルの削除
files.mkdir	フォルダの作成
files.rename	名前の変更
backups.create	バックアップの作成
backups.restore	バックアップの復元
key.create	API キーの発行
key.revoke	API キーの無効化

アカウント

API キーと、キーを発行したアカウントの情報を取得できます。キーの動作確認に使用できます。メンテナンス中もご利用いただけます。

アカウントと API キーの情報の取得

GET /me

必要な権限閲覧 read

key.abilities には、この API キーに付与されている権限のコードが入ります。

パラメーター

パラメーターはありません。

リクエストの例

curl

curl -sS https://pcs-cloud.jp/api/v1/me \
  -H "Authorization: Bearer $PCS_API_KEY"

レスポンスの例（200）

JSON

{
  "name": "yamada",
  "pass_active": true,
  "pass_until": "2026-10-29T18:42:10+09:00",
  "key": {
    "name": "GitHub Actions",
    "prefix": "pcs_3f9a1c2b…",
    "requests_count": 1284,
    "abilities": ["read", "power", "files.write"]
  }
}

主なエラー

missing_key invalid_key pass_required

名前	内容
name	アカウント名
pass_active	PCS PASS の加入状況
pass_until	PCS PASS の期限
key.name	API キーの名前
key.prefix	API キーの先頭の文字（確認用）
key.requests_count	この API キーでのリクエストの回数
key.abilities	この API キーの権限（権限の code）

Webhook

サーバーの停止・復帰などのイベントが発生すると、登録した URL へ JSON を POST で送信します。通知先の URL と通知するイベントは、アカウント設定の「PCS API・Webhook」で登録します。

通知先	https:// で始まる公開 URL（ポートは 443 のみ）。同時に5個まで有効にできます。
待ち時間	応答を3秒まで待ちます。リダイレクトには従いません。
自動停止	2xx 以外の応答や、送信できない宛先（名前解決できない・内部のアドレスを指す場合など）への送信の失敗が20回続くと、その Webhook を停止します。停止した Webhook は、アカウント設定から再開するまで送信しません。
配信の状況	API の利用状況のページで確認できます。

Discord への通知

Discord の Webhook URL には対応していません。Discord での通知には、アカウント設定の「Discord 通知」をご利用ください。

イベント

event	名称	送信のタイミング	data の内容
core.server.down	停止の検知	死活監視でサーバーの停止を検知したとき	data`server_id` `name` `type` `auto_restarted`
core.server.up	復帰の検知	停止を検知したサーバーの稼働を確認したとき	data`server_id` `name` `type` `down_since`
core.server.created	サーバーの作成	サーバーの作成が完了したとき	data`server_id` `name` `type` `plan` `connect`
core.server.renewed	自動更新	月額のサーバーを自動更新したとき	data`server_id` `name` `type` `active_until`
core.server.suspended	ご利用の停止（期限切れ・残高不足）	契約期間の終了・残高の不足により、ご利用を停止したとき	data`server_id` `name` `type` `reason`（`expired`・`balance`）`children`（プレミアムの契約元のみ）
ping	テスト送信	アカウント設定からテスト送信したとき	data`message`

停止の検知・復帰の検知は、死活監視を ON にしているサーバーが対象です。死活監視は数分ごとに行います。type は bot または minecraft です（PCS WEB のサイトの停止の検知・復帰の検知・自動更新では web）。プレミアムの契約元のご利用を停止した場合は、一緒に停止した bot のサーバー ID を children に含めます。

送信する内容

ヘッダー	内容
Content-Type	`application/json`
User-Agent	`PCS-Webhook/1`
X-PCS-Event	イベント名（例: `core.server.down`）
X-PCS-Signature	本文の署名（下記）

JSON

{
  "event": "core.server.down",
  "sent_at": "2026-10-02T14:05:00+09:00",
  "data": {
    "server_id": 1482,
    "name": "music-bot",
    "type": "bot",
    "auto_restarted": true
  }
}

署名の検証

X-PCS-Signature は、受信した本文を署名シークレット（whsec_ で始まる値）で HMAC-SHA256 により計算した値を、16進数の小文字で表したものです。署名シークレットは、アカウント設定の各 Webhook に表示されます。

署名は、受信した本文（バイト列）そのものから計算してください。JSON を読み込んでから文字列に戻すと一致しません。

Python

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["PCS_WEBHOOK_SECRET"].encode()  # whsec_ で始まる署名シークレット


@app.post("/pcs-webhook")
def pcs_webhook():
    body = request.get_data()  # 受信した本文（バイト列）
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-PCS-Signature", "")):
        abort(401)

    payload = request.get_json()
    if payload["event"] == "core.server.down":
        print("停止を検知しました:", payload["data"]["name"])
    return "", 204

稼働バッジ

サーバーの稼働状況を表示する画像（SVG）です。GitHub の README や Web サイトに掲載できます。PCS PASS 会員のサーバーが対象で、表示に API キーは必要ありません。

サーバーが稼働している場合

サーバーが起動の処理中の場合

サーバーが停止している場合

停止の処理中の場合や、死活監視の結果がない場合

PCS PASS のご利用期間外の場合や、URL が正しくない場合

バッジの URL は、サーバー管理画面の「利用状況」ページ、または GET /servers の badge_url で確認できます。

バッジには死活監視の結果を表示します（数分ごとに更新）。死活監視を OFF にすると更新されません。

PCS PASS のご利用期間が終了すると、バッジの表示は「PCS PASS限定」に変わります。PCS PASS に再度ご加入いただくと、同じ URL のまま稼働状況の表示に戻ります。

HTML

<img src="https://pcs-cloud.jp/badge/core/3f2c9a1e-7b4d-4c1a-9e52-8d0f6a2b71c4.svg" alt="PCS">

Markdown

![PCS](https://pcs-cloud.jp/badge/core/3f2c9a1e-7b4d-4c1a-9e52-8d0f6a2b71c4.svg)

エラー

エラーは、HTTP ステータスと code で判定してください。認証に関するエラー（missing_key・invalid_key・pass_required・banned・legal_consent）は、すべてのエンドポイントで返すことがあります。

ステータス	code	error
401	missing_key	API キーが指定されていません。Authorization ヘッダーに API キーを指定してください。
401	invalid_key	API キーが無効です。アカウント設定で有効な API キーをご確認ください。
402	balance_short	ウォレットの残高が不足しているため、起動できません。起動には50円以上の残高が必要です。金額は実際の値です。`required_yen`（必要な金額）と `balance_yen`（現在の残高）を含めます
403	pass_required	PCS API は PCS PASS 会員向けの機能です。API キーは保存されており、PCS PASS にご加入いただくとそのままご利用いただけます。`pass_url`（PCS PASS のご案内）を含めます
403	banned	このアカウントは利用停止中です。
403	legal_consent	利用規約・プライバシーポリシーの改定について、同意のお手続きをお願いしております。サイトにログインのうえ、ご確認ください。GET 以外のリクエストで返します
403	insufficient_scope	この API キーには「電源の操作」の権限がありません。必要な権限を付与した API キーをアカウント設定で発行してください。`required`（必要な権限の code）を含めます。従来の API キーでログ・操作の履歴を取得した場合は「従来の API キーでは、ログと操作の履歴を取得できません。アカウント設定で権限を選んで発行した API キーをご利用ください。」を返します（`required` は `scoped`）
403	suspended	このサーバーはご利用を停止しているため、操作できません。理由が判明している場合は「（理由: 契約期間の終了）」「（理由: 残高の不足）」などを続けます
403	cancelled	このサーバーは解約済みのため、操作できません。
403	expired	ご契約の期間が終了しているため、操作できません。契約を更新してから操作してください。
403	forbidden	この操作は許可されていません。
404	not_found	指定された URL またはサーバーが見つかりません。ファイル・フォルダ・バックアップが見つからない場合は「指定されたファイルが見つかりません。」「指定されたフォルダが見つかりません。」「指定されたバックアップが見つかりません。」を返します
405	method_not_allowed	この HTTP メソッドには対応していません。
409	pending	このサーバーは準備中のため、操作できません。準備の完了後に操作してください。
409	already_exists	同じ名前のファイルまたはフォルダがすでにあります。フォルダの作成・名前の変更で返します
409・503	busy	このサーバーではバックアップの処理を実行中です。完了までお待ちください。バックアップの作成・復元の処理中と、復元中の起動・再起動・ファイルの変更で返します。同じアカウントのほかのサーバーで処理中の場合は「このアカウントのほかのサーバーでバックアップの処理を実行中です。完了してから再度お試しください。」（`scope` は `account`）、全体で混み合っている場合は 503 と Retry-After を返します（「ただいまバックアップの処理が混み合っています。しばらく時間をおいてから再度お試しください。」）
413	file_too_large	テキストとして取得できるファイルは 1 MB までです。/files/download をご利用ください。
413	too_large	ファイルのサイズが上限を超えています。アップロード・ダウンロードできるファイルは 25 MB までです。ダウンロードするファイルが 25 MB を超える場合と、リクエストの本文が大きすぎる場合に返します。25 MB を超えるファイルのアップロードは `validation` を返します
413	too_many_entries	フォルダ内の項目が多すぎるため、操作できません。`path`（対象のフォルダ）を含めます
422	validation	action には start・stop・restart・kill のいずれかを指定してください。文言はパラメーターごとに異なります。`errors` にパラメーターごとの内容を含めます
422	no_fields	変更する項目を1つ以上指定してください。
422	invalid_path	path に使用できない文字が含まれています。「path に .. は使用できません。」「path は512バイト以内で指定してください。」も返します
422	root_not_allowed	ルートディレクトリ（/）は指定できません。
422	invalid_filename	ファイル名に使用できない文字が含まれています。
422	not_a_file	指定されたパスはファイルではありません。
422	symlink	シンボリックリンクは操作できません。
422	binary_file	バイナリファイルの内容は取得できません。/files/download をご利用ください。
422	start_file_not_found	指定された起動ファイルが見つかりません。
422	start_file_not_supported	マイクラサーバーでは起動ファイルを変更できません。起動ファイルを変更できない種類のサーバーでは「このサーバーでは起動ファイルを変更できません。」を返します
422	proxy_mode	プロキシモードの使用中は起動ファイルを変更できません。
429	rate_limited	リクエストの回数が上限に達しました。しばらく時間をおいてから再度お試しください。`retry_after`（秒）と Retry-After ヘッダーを含めます
429	transfer_limit	本日のファイルの転送量が上限に達しました。日付が変わってから再度お試しください。1日 2 GB まで（日本時間の0時に戻ります）
500	server_error	サーバーでエラーが発生しました。時間をおいて再度お試しください。
502	upstream_unavailable	サーバーの状態を取得できませんでした。時間をおいて再度お試しください。
502	upstream_error	ファイルの操作に失敗しました。時間をおいて再度お試しください。操作に応じて「電源の操作に失敗しました。」「設定の変更に失敗しました。」「バックアップの処理に失敗しました。」などで始まる文言を返します
503	maintenance	メンテナンス中のため、PCS API は現在ご利用いただけません。`ends_at`（終了予定の日時）を含めます。/me はメンテナンス中もご利用いただけます
503	upstream_busy	ただいま混み合っているため、処理を受け付けられませんでした。しばらく時間をおいてから再度お試しください。`retry_after`（秒）と Retry-After ヘッダーを含めることがあります
503	unavailable	ファイルとバックアップの操作は、現在ご利用いただけません。

上記以外のエラーでは、code に http_ とステータスコードを続けた値（例: http_400）を返すことがあります。

パラメーターの誤り（422）

JSON

{
  "error": "action には start・stop・restart・kill のいずれかを指定してください。",
  "code": "validation",
  "errors": {
    "action": ["action には start・stop・restart・kill のいずれかを指定してください。"]
  }
}

回数の上限（429）

JSON

{
  "error": "リクエストの回数が上限に達しました。しばらく時間をおいてから再度お試しください。",
  "code": "rate_limited",
  "retry_after": 42
}

利用制限

リクエストの回数は、操作の種類ごとに数えます。上限は API キーごとの回数と、同じアカウントの API キーを合わせた回数の2つです。

対象	API キーごと	アカウント全体
閲覧/me・サーバーの一覧と詳細・使用量・ログ・バックアップの一覧・操作の履歴	API キーごと1分間に60回	アカウント全体1分間に120回
電源の操作	API キーごと1分間に10回	アカウント全体1分間に20回
設定の変更	API キーごと1分間に20回	アカウント全体1分間に40回
ファイルの一覧・内容の取得	API キーごと1分間に60回	アカウント全体1分間に120回
ファイルのダウンロード	API キーごと1分間に20回	アカウント全体1分間に40回
ファイルの書き込み書き込み・アップロード・削除・フォルダの作成・名前の変更	API キーごと1分間に30回	アカウント全体1分間に60回
バックアップの作成・復元	API キーごと10分間に3回	アカウント全体10分間に6回
サーバーに接続する操作の合計/me・サーバーの一覧・操作の履歴を除くすべて。ファイルの削除は、確認するフォルダの数も数えます	API キーごと1分間に60回	アカウント全体1分間に90回
ファイルの転送量内容の取得・書き込み・アップロード・ダウンロードの合計	API キーごと—	アカウント全体1日 2 GB

上限に達すると 429 rate_limited を返します。再度リクエストできるまでの秒数を、Retry-After ヘッダーと retry_after に含めます。
応答には、X-RateLimit-Limit・X-RateLimit-Remaining ヘッダーを含めます。
誤った API キー（存在しない、または無効にした API キー）でのリクエストが、同じ接続元（IPv6 は /64 ごと）から1分間に30回に達すると、その接続元からの誤った API キーでのリクエストには、最大1分間 429 rate_limited を返します。有効な API キーでのリクエストには影響しません。
PCS 全体が混み合っている場合は、503 upstream_busy を返すことがあります。状態の確認などの閲覧は、電源の操作・変更の操作より先に制限されます。

利用規約に反するご利用は、利用規約に基づく措置の対象となります。

更新履歴

日付	内容
2026年9月27日	PCS API を公開しました。電源の操作に加え、使用量・ログの取得、設定の変更、ファイルとバックアップの操作、操作の履歴、API キーごとの権限の設定に対応しました。

PCS API_

概要

共通仕様

HTTP ステータス

認証と API キー

権限

閲覧専用のキー

クイックスタート

API キーの発行

キーの確認

サーバーの操作

discord.py から操作する

エンドポイント一覧

サーバー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

フィールド

値の一覧

電源の操作

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

使用量とログ

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

設定の変更

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

ファイル

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

パラメーター

リクエストの例

レスポンスの例（200）

主なエラー

GitHub Actions からの反映

バックアップ

パラメーター

リクエストの例