Skip to content

README.md

Latest commit

 

History

History
307 lines (234 loc) · 10.2 KB

README.md

File metadata and controls

307 lines (234 loc) · 10.2 KB
Raw

Karotter API Reference

Karotter (カロッター) の非公式 API リファレンス

Status Endpoints Auth Realtime License: MIT

フロントエンド JS バンドル解析 + 実 API テスト + セキュリティ診断レポートから作成した都度更新ドキュメント。

⚠️ 注意: 恐らく仕様変更が入っていますが対応できていません。単に Bot を作りたいだけなら karotter-selfbot を検討してください。

概要

Karotter (カロッター) の非公式 API リファレンス。フロントエンドの JS バンドル解析、実際の API テスト、セキュリティ診断レポート、および公式ドキュメントに基づいて作成しています。

特徴

項目 内容
エンドポイント 14 カテゴリ、約 145 件
認証 API キー / Cookie
リアルタイム Socket.IO イベント ~45 種
作成元 JS バンドル解析 + 実 API テスト + セキュリティ診断
対象 karotter.com / karotter.jp

Base URL

用途 Base URL
セルフBot (自アカウント操作) https://api.karotter.com/api/
開発者向け (第三者アプリ) https://api.karotter.com/api/developer

https://karotter.com/api でもアクセス可能（Cloudflare経由）

共通ヘッダー

全リクエストに以下のヘッダーを付与する。

ヘッダー 値 必須 備考
X-Client-Type web 推奨 web 以外でも動作するがアカウント凍結リスクあり
X-Device-Id UUID v4 推奨 セッション識別用、固定値でOK
X-CSRF-Token CSRFトークン 書き込み系 POST/PUT/DELETE で必要

認証方式

方式1: APIキー認証 (開発者向け)

Authorization: Bearer {apiKey}
  • /apikeys エンドポイントで発行可能

方式2: Cookie認証 (セルフBot)

Cookie: {ログイン時に返却されるCookie}
  • ログインレスポンスの Set-Cookie をそのまま使用

レート制限

レスポンスヘッダー: ratelimit-policy, ratelimit-limit, ratelimit-remaining, ratelimit-reset

エンドポイント 制限
POST /auth/login 5 req / 60s
POST /follow/{id} 5 req / 60s
POST /contact 5 req / 3600s
POST /reports 10 req / 900s
PATCH /users/profile 15 req / 60s
POST /posts/{id}/like, /react, /bookmark, /rekarot 30 req / 60s
POST /posts 50 req / 3600s
その他全般 100 req / 60s

HTTPステータスコード

コード 意味
200 成功
201 作成成功 (投稿、メッセージ等)
400 バリデーションエラー
401 未認証 / トークン無効
403 権限なし
404 リソースが見つからない
409 競合 (重複操作等)
429 レート制限超過
500 サーバー内部エラー

エラーレスポンス形式

// バリデーション・ビジネスエラー
{"error": "メッセージ", "status": 400}

// 認証エラー
{"error": "無効なトークンです"}

// 権限エラー
{"error": "このカロートを削除する権限がありません", "status": 403}

// 管理者権限
{"error": "管理者権限が必要です", "status": 403}

ファイル構成

ファイル 説明
endpoints/auth.md 認証 (ログイン、登録、セッション管理等)
endpoints/posts.md 投稿 (作成、取得、編集、削除、いいね、リアクション、投票、リカロート、ブックマーク)
endpoints/users.md ユーザー (プロフィール、設定、アカウント管理)
endpoints/follow.md フォロー (フォロー、ブロック、ミュート)
endpoints/notifications.md 通知
endpoints/dm.md ダイレクトメッセージ
endpoints/search.md 検索 (統合、投稿、ユーザー、ハッシュタグ、トレンド、ディスカバー)
endpoints/social.md ソーシャル (サークル、リスト、ストーリー、リンクプレビュー)
endpoints/draw.md Draw-chat (絵チャ)
endpoints/radio.md ラジオ / スペース
endpoints/admin.md 管理パネル
endpoints/developer.md Developer API
endpoints/other.md 規約、通報、お問い合わせ、APIキー、埋め込み
endpoints/socket.md Socket.IO リアルタイム通信
responses/post.md 投稿レスポンス構造
responses/notification.md 通知グルーピング構造
examples/python.md Python Bot 実装例

APIドメイン

ドメイン 状態 HSTS
api.karotter.com Active (プライマリ) max-age=0 (無効)
api.karotter.jp Active (ミラー) max-age=31536000
apikarotter.karon.jp Active (ミラー) max-age=15552000
api.karotter.net DNS解決不可 -
  • 3ドメインは同一バックエンド。トークンはクロスドメインで有効
  • Socket.IO も全ドメインで利用可能

CORS許可オリジン

karotter.com, karotter.jp, karotter.net, karotter.karon.jp, apikarotter.karon.jp, http://localhost:5173 (dev)

技術スタック

項目 詳細
Backend Node.js (Express) + Prisma
Database PostgreSQL
Frontend Vite + React
CDN/WAF Cloudflare
リアルタイム Socket.IO (WebSocketのみ)
認証 JWT (HS256) + CSRF
SSL Let's Encrypt

Cookie / LocalStorage

Cookie

名前 説明
karotter_at アクセストークン
karotter_rt リフレッシュトークン
karotter_csrf CSRFトークン

LocalStorage

キー 説明
karotter:accounts マルチアカウント一覧
karotter:active-account-id アクティブアカウントID
deviceId デバイス識別子
theme テーマ (light/dark)
locale 言語 (ja/en)
appearance-settings-v1 外観設定 (fontScale, uiScale等)
karotter-call-settings 通話設定
karotter:post-drafts:${userId} 下書き
push-notifications-enabled プッシュ通知ON/OFF

フロントエンドルート

メイン

パス ページ
/ ホーム/タイムライン
/login ログイン
/register 登録
/search 検索
/notifications 通知
/notifications/grouped-posts グループ化通知
/follow-requests フォローリクエスト
/bookmarks ブックマーク
/settings 設定
/profile/:username ユーザープロフィール
/posts/:id 投稿詳細
/:username/status/:id 投稿パーマリンク
/dm DMグループ一覧
/dm/:groupId DMチャット
/social サークル/リスト
/draw-chat 絵チャロビー
/draw-chat/rooms/:roomId 絵チャルーム
/spaces スペース一覧
/spaces/:spaceId スペース詳細
/report 通報
/contact お問い合わせ

法的ページ

/terms, /privacy, /cookie-policy, /ai-policy, /enforcement-policy, /child-safety-policy, /api-bot-terms, /creator-monetization-terms, /repeat-infringer-policy, /account-memorial-inheritance-policy, /business-transfer-data-succession-policy

注意事項

  • /api/users/me は「me」というユーザー名を検索する (現在のユーザーは /api/auth/me)
  • 同様に /api/users/settings, /api/users/notifications 等もユーザー名として解釈される
  • 画像アップロードのフィールド名: 投稿は media、DMは attachments (間違えると500)
  • 画像と動画の同時投稿不可 (400)
  • Cookie認証 (karotter_at, karotter_rt) が一部エンドポイントで必要。requests.Session() で自動処理

メディア

メディアURLの構造

画像: /uploads/posts/{uuid}.{ext}
DM添付: /uploads/dm/{uuid}.{ext}
アバター: /uploads/avatars/avatar_{userId}_{timestamp}.webp
ヘッダー: /uploads/headers/header_{userId}_{timestamp}.webp

フルURL: https://karotter.com{path}

メディアフィールド (投稿)

{
  "mediaUrls": ["/uploads/posts/uuid.png"],
  "mediaTypes": ["image"],
  "mediaAlts": [""],
  "mediaSpoilerFlags": [false],
  "mediaR18Flags": [false]
}
  • mediaTypes: "image" / "video"

メディアフィールド (DM)

{
  "attachmentUrls": ["/uploads/dm/uuid.png"],
  "attachmentTypes": ["image/png"],
  "attachmentAlts": [""],
  "attachmentSpoilerFlags": [false],
  "attachmentR18Flags": [false]
}
  • フィールド名が投稿とは異なる (media* vs attachment*)
  • attachmentTypes は MIME type (image/png 等)

クエリパラメータ

多くのエンドポイントで以下のパラメータが使用可能。

ページネーション

Offset方式 (従来):

?page=1&limit=15

Cursor方式 (推奨、無限スクロール用):

?limit=12&cursor={lastId}
  1. 初回は cursor なしでリクエスト → 最新N件を取得
  2. レスポンスの最後の投稿IDを cursor に指定 → それ以前のデータを取得
  3. データの重複なく過去を遡れる

ライセンス

MIT License — 詳細は LICENSE を参照。