公開APIリファレンス
チケット、メッセージ、アクションのエンドポイントと例。
スコープ付きAPIキーで、オムニチャネルのチケットとアクションをシステムから管理します。
ベースURL
すべてのリクエストは公開ゲートウェイ経由です。
https://api.threada.ai認証
- `X-Api-Key` ヘッダーでAPIキーを送信します。
- Admin → API keys でキーを作成/ローテーションし、統合ごとに1つ使用します。
- キーはテナント単位で、スコープによる最小権限を適用します。
スコープ
- `support.read` — チケット、メッセージ、アクションの一覧/取得。
- `support.write` — チケットの作成/更新とメッセージ追加。
- `support.actions` — アクションの実行と状態確認。
ページネーション
- 一覧エンドポイントは `limit` と `page_token` を受け付けます。
- `next_page_token` を次のリクエストに渡してください。
エラー
- エラーは `{ error: { type, message, code } }` を返します。
- HTTPステータスは `code` の値に対応します。
リクエスト/レスポンス例
チケット一覧
全チャネルのオープンなチケットを取得します。
リクエスト
curl -X GET "https://api.threada.ai/api/v1/public/tickets?limit=25" \
-H "X-Api-Key: YOUR_API_KEY" レスポンス
{
"items": [
{
"ticket_id": "TICKET_ID",
"tenant_id": "TENANT_ID",
"subject": "SUBJECT",
"status": "open",
"priority": "normal",
"channel": "email",
"tags": ["vip", "returns"],
"last_message_at": "2026-02-04T18:32:11Z"
}
],
"next_page_token": "NEXT_PAGE_TOKEN"
}チケット作成
初期メッセージ付きで新しいチケットを作成します。
リクエスト
curl -X POST "https://api.threada.ai/api/v1/public/tickets" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "SUBJECT",
"priority": "normal",
"channel": "email",
"contact": {
"name": "CUSTOMER_NAME",
"email": "customer@example.com"
},
"tags": ["returns"],
"initial_message": {
"role": "user",
"content": "MESSAGE_BODY",
"external_message_id": "EXT_MSG_ID"
}
}' レスポンス
{
"ticket": {
"summary": {
"ticket_id": "TICKET_ID",
"tenant_id": "TENANT_ID",
"subject": "SUBJECT",
"status": "open",
"priority": "normal",
"channel": "email",
"tags": ["returns"],
"created_at": "2026-02-04T18:32:11Z"
},
"contact": {
"name": "CUSTOMER_NAME",
"email": "customer@example.com"
},
"messages": [
{
"message_id": "MESSAGE_ID",
"role": "user",
"content": "MESSAGE_BODY",
"channel": "email",
"created_at": "2026-02-04T18:32:11Z"
}
]
}
}アクション実行
チケットに対してカスタムHTTP自動化を実行します。
リクエスト
curl -X POST "https://api.threada.ai/api/v1/public/tickets/TICKET_ID/actions" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"type": "custom_http",
"method": "POST",
"url": "/hooks/zapier",
"headers": {
"X-Source": "threada"
},
"body_json": "{\"event\":\"ticket_updated\"}"
}
}' レスポンス
{
"action": {
"action_id": "ACTION_ID",
"tenant_id": "TENANT_ID",
"ticket_id": "TICKET_ID",
"action_type": "custom_http",
"status": "succeeded",
"requested_by": "api_key:API_KEY_ID",
"payload": {
"type": "custom_http",
"method": "POST",
"url": "/hooks/zapier",
"headers": {
"X-Source": "threada"
},
"body_json": "{\"event\":\"ticket_updated\"}"
}
}
}