APIリファレンス
Letterflowの一覧と定義の取得、実行の開始と状態確認、各ステップのリージョン入力・出力の確認ができます。
TinkererのキーはLetterbox履歴の読み取り、ピン留め、削除に使えます。Aspiringでは該当スコープを選ぶと定義の読み取り、実行、状態の取得もできます。新しいキーの初期権限はLetterboxの読み取りのみです。実行権限だけでは状態や結果を取得できません。
概要
認証
APIキーを 設定 → 連携APIキー で生成します。Authorizationヘッダーに作成したトークンを含めてください:
キーごとに対象リソースと操作の権限を選択します。新しいキーはレターボックスの読み取りのみ許可されます。実行、状態の確認、ピン留め、削除には、それぞれの権限が必要です。
Authorization: Bearer hato_live_<token>
レート制限とキャッシング
API キーは送信元 IP に関係なく 1 分間に 30 リクエストまで使用できます。メタデータは ETag による条件付きリクエストに対応しています。リージョンのアクセス URL は 5 分以内に有効期限が切れ、コンテンツの保持期限も適用されます。
エラーフォーマット
エラーは、エラーコードとわかりやすいメッセージを含む標準JSONオブジェクトとして返されます:
{"error": {"code": "unauthorized", "message": "A valid Bearer API key is required."}}
保存済みの定義
limitとcursorで自分のLetterflowをページ単位で取得します。詳細にはメタデータ、準備状態、リージョン入力への署名付きリンクが含まれます。秘密鍵とアカウント認証情報は含まれません。
| エンドポイント | API の権限 |
|---|---|
GET /api/v1/letterflows/GET /api/v1/letterflows/{id}/ | letterflows:read |
実行の開始と状態の確認
空のJSONオブジェクトをPOSTすると保存済みLetterflowをすぐ実行します。Idempotency-Keyは実行ごとに新しく指定してください。同じキーの再送は同じ実行を返します。入力の上書きやAPIでのスケジュール設定には対応していません。
| エンドポイント | API の権限 |
|---|---|
POST /api/v1/letterflows/{id}/runs/ | letterflows:run |
GET /api/v1/runs/{uuid}/ | runs:read |
新しい実行は202とLocationポーリングURLを返し、同じ冪等性キーでの再送は200を返します。状態はwaiting、queued、running、completed、failedです。waitingはアカウントの利用枠をまだ予約していない状態、queuedは実行枠を割り当て済みでリージョンでの実行を待つ状態です。letterbox_urlが利用可能になったら参照してください。すべての送信に実行準備状態とプランの上限が適用されます。
実行状態のポーリングにはqueue_position、wait_reason、admitted_atが含まれます。待機キューが満杯の場合は429とerror.code=queue_fullを返します。受け付け済みの冪等性キーはキャンセル後も常に同じ実行を返すため、新しい配達には新しいキーを使用してください。
配達キュー →curl -X POST -H "Authorization: Bearer $HATO_API_KEY" \
-H 'Idempotency-Key: example-run-001' -H 'Content-Type: application/json' \
--data '{}' 'https://hato-api.example/api/v1/letterflows/7/runs/'
Letterflowのステップを確認
ステップの URL には value1 などのユーザー定義コンポーネント ID を使います。ID は大文字と小文字を区別し、実行時に固定されたスナップショットから解決されます。後で名前を変更しても、過去の実行へのアクセスは変わりません。
GET /api/v1/letterbox/{id}/steps/
GET /api/v1/letterbox/{id}/steps/{step_id}/
GET /api/v1/letterbox/{id}/steps/{step_id}/input/
GET /api/v1/letterbox/{id}/steps/{step_id}/output/
GET /api/v1/letterbox/{id}/steps/{step_id}/request-headers/
GET /api/v1/letterbox/{id}/steps/{step_id}/request-body/
GET /api/v1/letterbox/{id}/steps/{step_id}/response-headers/
GET /api/v1/letterbox/{id}/steps/{step_id}/response-body/
GET /api/v1/letterbox/{id}/steps/{step_id}/request-metadata/
GET /api/v1/letterbox/{id}/steps/{step_id}/value/
ステップの確認には letterbox:read が必要で、指定リージョンにリダイレクトされます。実行されたコンポーネントは実行順に表示され、その後にスキップされたコンポーネントが続きます。スキップされた入力は読み取れますが、生成されなかった出力は 404 を返します。保存済みの結果を再評価することはありません。
バリューの出力はテキスト、条件の出力は真偽値です。大きなバリューには result_url が返され、レターのステップには記録されたリクエストとレスポンスのアーティファクトへのリンクが返されます。期限切れのコンテンツは 410 を返します。
Letterステップのメタデータには、記録があればhttp_versionが含まれます。これはクライアントの希望設定ではなく、最終レスポンスで合意されたプロトコルです。
Bearer キーは Hub にのみ送信してください。リージョンのアクセス URL は、API キーを転送せず、別のリクエストで取得してください。
Letterbox一覧はletterflow_idとrun_idで絞り込めます。source_type（letter、condition、value、email）は最終コンポーネントの結果の種類です。
一覧
レターボックスのレスポンスメタデータを最新順にカーソルページネーションで取得します。
| Authorization必須 | Bearer hato_live_... |
| If-None-Match | 304条件付きキャッシュ検証用の任意のETag。 |
| パラメータ | 説明 |
|---|---|
| limitinteger | 取得するレコード件数（1〜100、デフォルト: 50）。 |
| cursorstring | 前のレスポンスから返された不透明なページネーションカーソル。 |
| sinceISO-8601 | 指定日時以降に送信されたエントリをフィルタ（例: 2026-08-01T00:00:00Z）。 |
| untilISO-8601 | 指定日時以前に送信されたエントリをフィルタ。 |
| letter_idinteger | 特定のLetter IDでエントリをフィルタ。 |
| source_typestring | 最終結果の種類で絞り込みます: letter、condition、value。 |
| status_codeinteger | HTTP/FTPレスポンスコードでフィルタ（例: 200, 404, 500）。 |
| pinnedboolean | ピン留め状態（'true' または 'false'）でフィルタ。 |
curl -H "Authorization: Bearer $HATO_API_KEY" \
"https://hato-api.example/api/v1/letterbox/?limit=20&pinned;=true"
{
"data": [
{
"id": 42,
"letterflow_id": 7,
"letterflow_name": "Health Check",
"source_type": "letter",
"run_id": null,
"steps_url": null,
"request": {
"method": "GET"
},
"response": {
"status_code": 200
},
"duration_ms": 142,
"sent_at": "2026-08-28T14:30:00+00:00",
"request_sent_at": "2026-08-28T14:30:00.010000+00:00",
"response_received_at": "2026-08-28T14:30:00.152000+00:00",
"is_pinned": true,
"bodies_pruned": false,
"error_message": "",
"region": "au",
"spoke_id": "spoke-au-1",
"artifact_available": true,
"request_headers_url": "https://spoke-au.example/artifacts/...",
"request_body_url": null,
"response_headers_url": "https://spoke-au.example/artifacts/...",
"response_body_url": "https://spoke-au.example/artifacts/..."
}
],
"next_cursor": "eyJzZW50X2F0IjoiMjAyNi0wOC0yOFQxNDozMDowMCIsImlkIjo0Mn0"
}
ピン留めされていないLetterbox履歴をすべて削除し、関連するリージョンのアーティファクトも削除します。Spokeが一時的に利用できない場合は、削除を再試行するためにキューへ登録します。
curl -X DELETE \
-H "Authorization: Bearer $HATO_API_KEY" \
"https://hato-api.example/api/v1/letterbox/"
IDを指定して単一のレターボックスレスポンスの完全なメタデータ（最新の署名付きリージョンアーティファクトURLを含む）を取得します。
| idinteger必須 | レターボックスエントリの一意なID。 |
curl -H "Authorization: Bearer $HATO_API_KEY" \
"https://hato-api.example/api/v1/letterbox/42/"
{
"data": {
"id": 42,
"letterflow_id": 7,
"letterflow_name": "Health Check",
"source_type": "letter",
"run_id": null,
"steps_url": null,
"request": {
"method": "GET"
},
"response": {
"status_code": 200
},
"duration_ms": 142,
"sent_at": "2026-08-28T14:30:00+00:00",
"request_sent_at": "2026-08-28T14:30:00.010000+00:00",
"response_received_at": "2026-08-28T14:30:00.152000+00:00",
"is_pinned": false,
"bodies_pruned": false,
"error_message": "",
"region": "au",
"spoke_id": "spoke-au-1",
"artifact_available": true,
"request_headers_url": "https://spoke-au.example/artifacts/read?token=...",
"request_body_url": null,
"response_headers_url": "https://spoke-au.example/artifacts/read?token=...",
"response_body_url": "https://spoke-au.example/artifacts/read?token=..."
}
}
レターボックスエントリをピン留めまたは解除します。ピン留めにより、レスポンスボディが有効期限切れやFIFO容量削除から保護されます。
| 項目 | 型 | 説明 |
|---|---|---|
| is_pinned必須 | boolean | ピン留めする場合は true、解除する場合は false を設定します。 |
curl -X PATCH \
-H "Authorization: Bearer $HATO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"is_pinned": true}' \
"https://hato-api.example/api/v1/letterbox/42/"
{
"data": {
"id": 42,
"letterflow_id": 7,
"letterflow_name": "Health Check",
"source_type": "letter",
"run_id": null,
"steps_url": null,
"request": {
"method": "GET"
},
"response": {
"status_code": 200
},
"duration_ms": 142,
"sent_at": "2026-08-28T14:30:00+00:00",
"request_sent_at": "2026-08-28T14:30:00.010000+00:00",
"response_received_at": "2026-08-28T14:30:00.152000+00:00",
"is_pinned": true,
"bodies_pruned": false,
"error_message": "",
"region": "au",
"spoke_id": "spoke-au-1",
"artifact_available": true,
"request_headers_url": "https://spoke-au.example/artifacts/read?token=...",
"request_body_url": null,
"response_headers_url": "https://spoke-au.example/artifacts/read?token=...",
"response_body_url": "https://spoke-au.example/artifacts/read?token=..."
}
}
単一のレスポンスレコードを完全に削除し、リージョンSpokeからの保存アーティファクトのクリーンアップを実行します。
| idinteger必須 | 削除するレターボックスエントリの一意なID。 |
curl -X DELETE \
-H "Authorization: Bearer $HATO_API_KEY" \
"https://hato-api.example/api/v1/letterbox/42/"
有効期間の短いリージョンURLへリダイレクトします。BearerキーはHubに送信し、リージョンのLocationにはキーを転送せず別のリクエストでアクセスしてください。コンテンツへのアクセス権は保持期間と所有権の確認に従います。
| idinteger必須 | レターボックスエントリID。 |
| artifactstring必須 | 次のいずれか: request-headers、request-body、response-headers、response-body。 |
curl -sS -D - -o /dev/null -H "Authorization: Bearer $HATO_API_KEY" \
"https://hato-api.example/api/v1/letterbox/42/response-body/"
curl -o response_payload.json "REGIONAL_LOCATION_URL"
HTTP/1.1 302 Found Location: https://spoke-au.example/artifacts/read?token=ey... Cache-Control: private, no-store
Directory
有料の連携キーでは、directory:readを明示的に選択して変数の一覧やリージョンの値URLを取得できます。秘密情報も含む権限で、自動的には付与されません。Directoryの変更はダッシュボードから行います。
GET /api/v1/directory/?region=au
GET /api/v1/directory/{id}/