REST API
現在REST APIはベータ版です。これは、特定のエンドポイントやAPIのレスポンスが変更される可能性があることを意味します。
認証
REST APIにはHTTPS経由でのみアクセスでき、すべてのリクエストにAPIトークン(アクセストークンとも呼びます)が必要です。トークンは、アカウント設定のSecurityタブで作成します。
APIトークンはユーザーアカウントに属します。Organizationには独自のトークンがないため、OrganizationのプロジェクトでAPIを呼び出すには、そのプロジェクトに参加しているユーザーアカウントのトークンを使用してください。
トークンの生成
- playcanvas.com/account/securityに移動します。または、プロジェクトダッシュボードでサイドバー下部の自分の名前を選択し、Account settingsを選んでSecurityタブを選択します。
- API tokensでGenerate tokenを選択します。
CI publishのように、トークンの用途がわかるNameを入力し、Generateを選択します。- Your new tokenにトークンが表示されます。Copyを選択してCIシステムのシークレットなどの安全な場所に保存し、Doneを選択します。トークンを再び表示することはできません。
トークンはREST APIであなたとして動作するため、秘密にしてください。ソース管理にコミットしたり、クライアント側のコードに含めたり、フォーラムに投稿したりしないでください。トークンが漏れた場合は、取り消して新しいトークンを生成してください。
トークンの管理
API tokensには、トークンがそれぞれの作成日とともに一覧表示されます。
- Renameでトークンの名前を変更します。
- Revokeでそのトークンを取り消します。
- Revoke allですべてのトークンを取り消します。
どちらの取り消しも、実行前に確認を求められます。取り消したトークンを使用しているスクリプトやツールは、すぐに動作しなくなります。
2026年11月5日より前に作成されたトークンは、2026年11月19日に使用できなくなります。スクリプトやツールで古いトークンを使用している場合は、新しいトークンを生成して置き換えてください。フォーラムのお知らせを参照してください。
トークンの使用
すべてのリクエストで、Authorizationヘッダーに次の値を設定します。
Bearer [access_token]
[access_token]をAPIトークンに置き換えてください。
以下に例を示します。
curl -H "Authorization: Bearer nesgdxhiqe7hylfilr6ss1rds0gq1uj8" https://playcanvas.com/api/...
パラメーター
さまざまなルートは、いくつかのパラメータを受け入れます。GETリクエストの場合、パラメータがURLの一部でない場合、HTTPクエリ文字列パラメータとして渡すことができます。POST、PUT、DELETEリクエストに含まれない場合は、Content-Typeが 'application/json' のJSONとしてエンコードする必要があります。
各エンドポイントで使用される共通のパラメータがいくつかあります:
project_id
プロジェクト概要ページのURLから見つけることができます。

scenes
エディタでシーンを開く場合、シーンIDはURLにあります。

branch_id
これはバージョン管理パネルで見つかり、選択してコピーできます。

レスポンスフォーマット
私たちのREST APIは、各API呼び出しの応答形式について、一般的なガイドラインに従っています。
単一リソースの取得
単一のリソースを取得しようとしている場合、応答はあなたが要求したリソースを持つJSONオブジェクトになります。
複数のリソースを取得
たとえば、プロジェクトのアプリをリストアップするような複数のリソースを取得しようとしている場合は、次の形式のJSONオブジェクトを取得します。
{
"result": [
resource_1,
resource_2,
...,
resource_N
],
"pagination": {
"limit": number,
"skip": number,
"total": number
}
}
レスポンスにはページネーションデータも含まれています。レスポンスのページネーションを制御するには、次のURLパラメータを渡すことができます。
| 名前 | 説明 |
|---|---|
limit | 応答に含めるアイテムの最大数。 |
skip | 元の結果セットからスキップする項目の数。 |
sort | 結果セットをソートするために使用するフィールドの名前。 |
order | 昇順で結果を取得したい場合は1を渡し、降順にするには-1を渡します。 |
たとえば、最初の16件のアイテムをスキップして、32件のアイテムを取得するには、次のリクエストを送信します。
https://playcanvas.com/api/items?limit=32&skip=16
エラー
エラーが発生した場合は、次の形式のJSONオブジェクトが表示されます。
{
"error": "エラーメッセージです。"
}
また、レスポンスのステータスコードも適切なHTTPエラーコードになります。
レート制限
Calls to the REST API have a rate limit. Check your actual limits by querying this endpoint. There are different rate limits depending on the request:
| Rate Limit Type | 説明 | Limit for free accounts | Limit for personal/org accounts |
|---|---|---|---|
| 法線 (Normal) | The normal rate limit | 120 requests/minute | 240 requests/minute |
| Strict | The strict rate limit | 5 requests/minute | 10 requests/minute |
| アセット (Asset) | The assets rate limit | 60 requests/minute | 120 requests/minute |
APIの呼び出し回数を調整するために、次のヘッダがレスポンスに含まれます。
| 名前 | 説明 |
|---|---|
X-RateLimit-Limit | The number of requests allowed in a minute. |
X-RateLimit-Remaining | The remaining number of requests that you are allowed to make this minute. |
X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds. |
レート制限を超過すると、 429 Too Many Requestsステータスコードを受け取ります。制限が解除されるまで、新しいリクエストを続けることはできません。