開発者API

Amplitude Developer APIは、プロジェクト、タクソノミー、機能フラグ、分析、宛先、実装スキル用のOpenAPI定義のREST APIです。これは、Amplitude CLIの背後にあるコントラクトです。

ベースURL

認証

ほとんどのDeveloper APIリクエストにはHTTP Bearerトークンが必要です。Authorizationヘッダーで送信します。

bash
Authorization: Bearer YOUR_ACCESS_TOKEN

Bearerトークンは、デバイスフローからのOAuthアクセストークンまたはパーソナルアクセストークン(PAT)のいずれかです。どちらも同じヘッダーとスコープモデルを使用しており、いずれもそのスコープが許可するエンドポイントを呼び出せます。デバイス認証、トークン交換、スキルエンドポイントでは、Bearerトークンを必要としません。

Get authenticated contextを呼び出して、トークンがどの認証情報タイプ、範囲、組織に解決されるかを確認します。principal.auth_typeフィールドはoauth、pat、service_account、またはapi_keyを返します。

OAuthデバイスフロー

デバイスフローを使用して、クライアントシークレットを埋め込むことなく、CLI、スクリプト、またはその他の入力制約付きクライアントを認証します。 このフローには、デバイス認証リクエストを開始する手順と、トークンをポーリングする手順の 2 つのステップがあります。

  1. デバイス認証リクエストを開始します。 必要なスペース区切りのscopeを、デバイス認可エンドポイントに送信します。このエンドポイントは Bearer トークンを必要としません。

    bash
    curl -X POST https://developer-api.amplitude.com/v1/auth/device-authorization \
      -H "Content-Type: application/json" \
      -d '{
        "scope": "projects:read analytics:read"
      }'
    

    レスポンスにはdevice_code、user_code、verification_uri(およびverification_uri_complete)、expires_in、およびポーリングintervalが含まれます。

  2. ユーザーにリクエストを承認するように指示します。 user_codeを表示し、ユーザーをverification_uriに送信する(またはverification_uri_completeを直接開く)ことで、ブラウザでリクエストを承認してもらいます。

  3. **トークンをポーリングします。**ユーザーがリクエストを承認している間、device_codeグラントを使用してトークンエンドポイントをポーリングします。

    bash
    curl -X POST https://developer-api.amplitude.com/v1/auth/token \
      -H "Content-Type: application/json" \
      -d '{
        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
        "device_code": "YOUR_DEVICE_CODE"
      }'
    

    ポーリングの間隔は、ステップ1で取得したintervalよりも短い頻度にしないでください。ユーザーがリクエストを承認すると、トークンエンドポイントはaccess_token、token_type、expires_in、refresh_token、scope、およびid_tokenを返します。以降のリクエストでは、Bearerトークンとしてaccess_tokenを送信します。

個人用アクセストークン

パーソナルアクセストークン(PAT)は、CIパイプラインや、デバイスフローを実行することが実用的でないその他の非対話型環境で使用される、長期間にわたるベアラ認証情報です。 OAuthアクセストークンと同じ方法で、PATをAuthorizationヘッダーで送信します。amp CLIは、amp auth loginの代わりに、既存のPATを非対話形式で受け入れます(例:amp auth pat --with-token)。

スコープ

連携に必要なスコープのみをリクエストします。 デバイス認証リクエストのscopeフィールドは、スペースで区切られたリストを受け入れます。PATには独自の固定スコープセットが含まれています。GET /v1/contextは、有効なトークンに付与されたスコープをprincipal.scopesに報告します。

必要なスコープがないトークンを持つリクエストは、403エラーを返します。共有のエラー形式については、表記規則を参照してください。

規則

ページネーション

リストエンドポイントは、cursorcursorクエリパラメータ(前のレスポンスのpagination.next_cursorから得られる不透明な値)と、limitlimitクエリパラメータ(デフォルト値50、最大値200)を受け入れます。各リストレスポンスには、paginationオブジェクトが含まれています:

json
{
  "pagination": {
    "next_cursor": "eyJvZmZzZXQiOjUwfQ",
    "has_more": true
  }
}

next_cursorAmplitudeは最後のページにnullあります。基盤となる検索インデックスは、クエリごとの結果を 10,000 件に制限しています。適切に構成されたページ分割はその上限の前に停止します。カーソルがその上限を超えたリクエストは、400エラーとerror_code: pagination_not_supportedを返します。

エラー

エラーレスポンスではRFC 9457の問題詳細を使用し、application/problem+jsonとして提供します:

json
{
  "type": "https://developer-api.amplitude.com/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "limit must be less than or equal to 200",
  "instance": "/v1/projects/abc123/charts",
  "error_code": "validation_error",
  "retryable": false,
  "retry_after_seconds": null,
  "validation_errors": null
}

retryable同じリクエストを再試行すると成功する可能性があるかどうかを示します。retryableがtrueの場合、retry_after_secondsバックオフが推奨されることがあります。リクエストの検証に失敗すると、validation_errors に値が入力されます。

冪等性

それを受け入れるリクエストには、Idempotency-Key8文字から255文字の間の一意の文字列が必要です。同じキーを再使用すると、重複するミューテーションのリスクなしで安全にリクエストを再試行できます。各エンドポイントのパラメータを確認して、このヘッダーを受け入れるかどうかを判断します。

試行

削除およびアーカイブ操作は、dry_runクエリパラメータ(デフォルト:false)を受け入れます。dry_run=true を設定して、変更を適用せずにライブ操作と同じチェックでリクエストを検証します。

これは役に立ちましたか?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

このページでは