Misskey API

MisskeyAPIを使ってMisskeyクライアント、Misskey連携Webサービス、Bot等(以下「アプリケーション」と呼びます)を開発できます。ストリーミングAPIもあるので、リアルタイム性のあるアプリケーションを作ることも可能です。

APIを使い始めるには、まずアクセストークンを取得する必要があります。このドキュメントでは、アクセストークンを取得する手順を説明した後、基本的なAPIの使い方を説明します。

アクセストークンの取得

基本的に、APIはリクエストにはアクセストークンが必要となります。あなたの作ろうとしているアプリケーションが、あなた専用のものなのか、それとも不特定多数の人に使ってもらうものなのかによって、アクセストークンの取得手順は異なります。

あなた専用の場合: 自分のアカウントのアクセストークンを使用してください
皆に使ってもらう場合: アプリケーションとしてアクセストークンを取得するを使用してください

自分のアカウントのアクセストークン (ネイティブトークン)

アカウントに1つ存在する、MisskeyのWebクライアントでも使われるアクセストークンです。
これは、各ユーザーの設定画面 (設定=>API)から取得できます。
ほとんど全ての操作ができる強力なアクセストークンです。

アプリケーションとしてアクセストークンを取得する

いわゆるサードパーティアプリ向けのWeb画面で権限を列挙してユーザーに承認してもらうタイプのアクセストークンです。

Step1 アプリケーションを作成する

まず API app/create を使用してアプリケーションを作成します。
APIの1つですので、リクエストはPOST / リクエストボディはJSON / レスポンスボディもJSONです。

リクエストJSON

{
  name: string;   // アプリケーション名 (必須)
  description: string; // アプリケーションの説明 (必須)
  permission: string[], // 権限の一覧 (必須ですが要素数0でも有効です, 後述)
  callbackUrl?: string; // コールバックURL (オプション, ユーザー承認後にリダイレクトされるURL)
}
// なお各項目には一意制約はありません

作成に成功すると作成されたアプリケーションの情報が返ってきます

レスポンスJSON

{
  id: string; // アプリケーションID (この後の認証フローでは使用しませんが、API `app/show` などに使用できます)
  name: string; // リクエストと同じ
  description: string; // リクエストと同じ
  callbackUrl?: string; // リクエストと同じ
  permission: string[]; // リクエストと同じ
  secret: string; // アプリケーションのシークレットキー (この後の認証フローで使用します)
}

Step2 認証セッションを作成する

API auth/session/generate で認証セッションを作成します

リクエストJSON

{
  appSecret: string; // アプリケーションのシークレットキー (Step1の`secret`になります)
}

成功すると以下の情報が返ってきます

レスポンスJSON

{
  token: string; // セッションのトークン
  url: string;   // ユーザーに認証させるURL
}

Step3 ユーザーに承認してもらう

Step2のurlにユーザーをアクセスさせてユーザーに承認してもらいます

承認が完了すると、
コールバックURLが定義されている場合は、<コールバックURL>?token=<セッションのトークン> にリダイレクトされます。
そうでない場合は何も行いませんので、ユーザーに認証完了後になんらかの入力してもらう等の方法で待機してから次のStepに進んでください。

Step4 ユーザーキーを取得する

API auth/session/userkey からユーザーキーを取得します

リクエストJSON

{
  appSecret: string; // アプリケーションのシークレットキー (Step1の`secret`になります)
  token: string; // セッションのトークン (Step2の`token`になります)
}

レスポンスJSON

{
  accessToken: string; // ユーザーキー
  user: object; // ユーザーの情報
}

Step5 アクセストークンを生成する

Step4のaccessToken と Step1のsecret を文字列として単純結合してSHA256したものが
APIリクエスト時のアクセストークン (iとして付与するもの) になります。

※ string => binary変換にエンコードを明示する必要がある場合はASCIIでもUTF-8でも構わない

APIの使い方

APIはすべてPOSTで、リクエスト/レスポンスともにJSON形式です。RESTではありません。 アクセストークンは、iというパラメータ名でリクエストボディのJSONに含めます。

{
    "i": "アクセストークン"
    // ：他のパラメーター
}

APIリファレンス

ストリーミングAPI

権限の一覧

permissionとして指定する権限の一覧と対応するエンドポイントは APIリファレンス#Permissions から確認できます。

v10とv11の権限には互換がありませんが、ここではv11互換の権限を指定すれば変換して承認を要求するようになっています。

いくつかのエンドポイントは、権限を要求しなくても使用できます。(リファレンスでは unspecified と区分されています)