メインコンテンツまでスキップ

REST API

警告

現在REST APIはベータ版です。これは、特定のエンドポイントやAPIのレスポンスが変更される可能性があることを意味します。

認証​

REST APIにはHTTPS経由でのみアクセスでき、すべてのリクエストにAPIトークン(アクセストークンとも呼びます)が必要です。トークンは、アカウント設定のSecurityタブで作成します。

APIトークンはユーザーアカウントに属します。Organizationには独自のトークンがないため、OrganizationのプロジェクトでAPIを呼び出すには、そのプロジェクトに参加しているユーザーアカウントのトークンを使用してください。

トークンの生成​

  1. playcanvas.com/account/securityに移動します。または、プロジェクトダッシュボードでサイドバー下部の自分の名前を選択し、Account settingsを選んでSecurityタブを選択します。
  2. API tokensでGenerate tokenを選択します。
  3. CI publishのように、トークンの用途がわかるNameを入力し、Generateを選択します。
  4. 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から見つけることができます。

Project ID

scenes​

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

Scene ID

branch_id​

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

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 accountsLimit for personal/org accounts
法線 (Normal)The normal rate limit120 requests/minute240 requests/minute
StrictThe strict rate limit5 requests/minute10 requests/minute
アセット (Asset)The assets rate limit60 requests/minute120 requests/minute

APIの呼び出し回数を調整するために、次のヘッダがレスポンスに含まれます。

名前説明
X-RateLimit-LimitThe number of requests allowed in a minute.
X-RateLimit-RemainingThe remaining number of requests that you are allowed to make this minute.
X-RateLimit-ResetThe time at which the current rate limit window resets in UTC epoch seconds.

レート制限を超過すると、 429 Too Many Requestsステータスコードを受け取ります。制限が解除されるまで、新しいリクエストを続けることはできません。