jointrashposs/content/en-US/docs/api/index.md

description
Misskey exposes an API that you can use to develop Misskey clients, Misskey-connected web services, bots, etc. ("Applications").

Misskey API

Misskey exposes an API that you can use to develop Misskey clients, Misskey-connected web services, bots, etc. ("Applications"). We also have a streaming API, so you can create applications with real-time capabilities.

::: tip By using the official Misskey SDK or third party libraries, you can use the API more conveniently, for example by simplifying some of the steps described in this document. See here for more information about libraries. :::

To start using the API, you will need to obtain an access token associated with the account you wish to use the API with. This document will walk you through the process of obtaining an access token and then show you how to use the API in a basic way.

Getting an access token

The API generally requires an access token to make a request. An access token is a set of credentials associated with a user, which identifies the user using the API and controls what operations each access token is authorised to perform.

::: tip There is a one-to-many relationship between a user and the access token associated with that user, and multiple access tokens can be issued for a given user. :::

You can easily obtain an access token for yourself, or you can obtain an access token for an user who will be using your application.

Manually issue an access token

You can issue your own access token in Misskey Web under 'Settings > API'.

::: danger Please do not share your access token with anyone. :::

Request an access token to be issued

To obtain an access token for a user of the application ( simply "the user"), you can request it to be issued in the following way.

::: tip The method described below is called MiAuth, ant it issues an instant access token without creating an app.

You can still create an app to obtain access token. :::

Step 1

Generate a UUID. This will be referred to as the session ID from now on.

::: danger This session ID should be generated each time and should not be reused. :::

Step 2

The application authentication form should be displayed in the user's browser. The authentication form can be opened with a URL similar to this:

https://{host}/miauth/{session}

where

• {host} is the host of the user's instance (usually this is entered by the user) and
• {session} is the session ID.

You can also set a few options as query parameters to the URL:

name	description
name	application name
icon	application icon image URL。
callback	The URL to which the user will be redirected after authentication, with the session ID added to the redirect with the query parameter session.
permission	The permissions that the application requires. List the permissions to be requested, separated by ,. The list of permissions can be found here.

::: tip Example

https://misskey.io/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f?name=MyApp&callback=https%3A%2F%2Fmyapp.example.com%2Fcallback&permisson=write:notes,write:following,read:drive

:::

Step 3

After the user has been granted application access, a POST request to a URL of the following form will return JSON containing the access token as a response.

https://{host}/api/miauth/{session}/check

where

• {host} is the host of the user's instance and
• {session} is the session ID.

The properties included in the response are as follows:

name	description
token	access token for the user
user	information about the user

Using the API

Once you have your API access token, you can use the API by making requests to the various endpoints.

::: tip

• All HTTP APIs are POST, and both request and response are in JSON format (excluding drive/files/create).
• Specify Content-Type: application/json in the request header.
• The access token is included in the request body JSON with the parameter name i.

:::

Example of a body with an access token (for meta):

{
    "i": "HogEFugA1341",
    "detail": false
}

The access token is included in the request body JSON at the parameter i.

For more information on the API, see the API Reference.

::: warning Misskey does not use REST. :::

In addition to the HTTP API, Misskey also provides a streaming API. More information about the streaming API can be found here.

::: tip Your Misskey instance also provides API documentation at /api-doc. :::