Postback API v2 は、次世代の Postback インジェストエンドポイントです。レガシー Postback API と同じ /postback/v3/event/{database}/{table} のパス契約を持ちますが、新しい records.in.treasuredata.com ホストから提供され、ヘッダーベース認証のみをサポートします。
Postback API v2 は、レガシー Postback API と同じユースケースに使用できます。カスタム Webhook、JS SDK や TD Logger を実行できない環境、または外部アプリケーションによってトリガーされるシングルレコードのインポートなどが該当します。
| レガシー Postback | Postback v2 | |
|---|---|---|
| ホスト | in.treasuredata.com | <region>.records.in.treasuredata.com |
X-TD-Write-Key ヘッダー | サポート | サポート |
Authorization: TD1 <key> ヘッダー | — | サポート |
?td_write_key=<key> URL パラメーター | サポート | 非サポート |
| 最大リクエストボディサイズ | — | 1,048,064 バイト |
| パス | /postback/v3/event/{db}/{table} | /postback/v3/event/{db}/{table} |
レガシーの URL パス API キー（?td_write_key=...）は v2 では受け付けられません。切り替え前に、このキーを使用しているクライアントを以下の2つのヘッダー形式のいずれかに移行してください。
- Write API キーの確認
- リージョンの Postback API エンドポイントの確認 — v2 ホストは
<region>.records.in.treasuredata.comです。 - 書き込みアクセス権を持つ TD データベースとテーブル。ここに API キーを使用してデータを書き込みます。
TD Write API キーをヘッダーとして追加し、データベースとテーブルを URL に指定し、リクエストボディにデータを含めます。JSON ペイロードとしてデータを送信してください。
| パラメーター | 説明 |
|---|---|
database | URL に宛先データベース名を指定します。英字・数字・_ のみ使用できます。 |
table | URL に宛先テーブル名を指定します。英字・数字・_ のみ使用できます。 |
v2 は2つのヘッダーベース認証方法をサポートしています。どちらか一方を選択してください。両方送信した場合は Authorization が優先されます。
# 1. Authorization ヘッダー（TD1 スキーム）
-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789'
# 2. X-TD-Write-Key ヘッダー
-H 'X-TD-Write-Key: 123/abcdef•••••••••••••••••••••••0123456789'curl -i -X POST 'https://us01.records.in.treasuredata.com/postback/v3/event/db_test/table_1' \
-H 'Content-Type: application/json' \
-H 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789' \
-d '{"email":"firstname.lastname@business.com","telephone":"555-555-5540"}'HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 May 2026 00:23:32 GMT
Strict-Transport-Security: max-age=31536000
Content-Length: 2
Connection: keep-alive
{}リクエストボディの上限は 1,048,064 バイト です。上限を超えるリクエストは 413 Payload Too Large で拒否されます。
レガシーエンドポイントと同様に、無効な API キーを使用したリクエストは同期的に 200 OK を返します。キーの検証はレスポンス送信後に非同期で実行されます。無効なキーは、HTTP レイヤーではなくインジェストパイプライン内で認証エラーとして表面化します。
- レガシー Postback API クイックスタート
- Treasure Toolbelt — Treasure AI サービス向けコマンドラインインターフェース
- JavaScript SDK クイックスタート