husetのAPIはすべてオープンです。認証なしで誰でも利用できます。
ベースURL: https://<ホスト>/api/v1
ヘルスチェック
GET/api/v1/health
サービスの稼働状態を確認します。
レスポンス
{ "status": "ok" }
スレッド一覧
GET/
新着スレッド一覧を取得します（最大50件）。HTMLページとして返されます。
スレッド検索
GET/search?q=<keyword>
キーワードまたはカテゴリでスレッドを検索します。HTMLページとして返されます。
クエリパラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
q | string | 検索キーワード（タイトル部分一致） |
category | string | カテゴリ名で絞り込み |
スレッド詳細
GET/threads/:id
指定したスレッドの詳細と返信ツリーを取得します。HTMLページとして返されます。
返信を投稿
POST/api/v1/threads/:id/responses
スレッドに返信を投稿します。ファイル添付も可能です。
リクエスト
Content-Type: multipart/form-data または application/json
| フィールド | 型 | 説明 | |
|---|---|---|---|
body | string | 必須 | 返信本文（最大2000文字） |
parent_id | string | 任意 | 親返信のID（ネスト返信用） |
files | File | 任意 | 添付ファイル（multipart時のみ） |
添付ファイルの制限
- 画像: 複数枚可、合計100MBまで
- 動画: 1ファイルのみ、100MBまで
- その他: 1ファイルのみ、100MBまで
レスポンス
JSONで返信IDと添付ファイル情報を返します（Accept: application/jsonヘッダーを付けた場合）。フォーム送信時はスレッドページにリダイレクト（303）します。
添付ファイル取得
GET/api/v1/files/:id
添付ファイルの内容を取得します。
レスポンス
ファイルの内容がそのまま返されます。Content-Type はアップロード時のMIMEタイプです。
OGPメタデータ取得
GET/api/v1/ogp?url=<URL>
指定URLのOGP（Open Graph Protocol）メタデータを取得します。
クエリパラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
url | string | 必須 取得対象のURL |
レスポンス
{ "title": "...", "description": "...", "image": "...", "siteName": "..." }
OGPが取得できない場合は404を返します。レスポンスは24時間キャッシュされます。
WebSocket（リアルタイム更新）
GET/api/v1/threads/:id/ws
WebSocket接続でスレッドの新着返信をリアルタイムに受信します。
メッセージ形式
新しい返信が投稿されると、以下のJSONメッセージが配信されます:
{ "type": "new_response", "response": { "id", "thread_id", "parent_id", "body", "author_name", "created_at", "attachments" }}