The Kitsu API implements the JSON:API specification. This means there are some notable semantics to how you consume it, but understanding it will take a lot of the work of using it out of your hands.

We have included a short overview of the capabilities, but you can consult the JSON:API Specification for more information.

You can be more specific about the data you want to retrieve by using URL parameters and are outlined below.

NOTE: This documentation will display parameters with brackets ([ and ]) for readability, but actual URLs will need to be percent-encoded (%5B and %5D).

As per the JSON:API specification, all requests to the API should contain these headers:

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Filtering lets you query data that contains certain matching attributes or relationships. These take the form of filter[attribute]=value.

For example, you can request all the anime of the Adventure category:

/anime?filter[categories]=adventure

For some models, you can also search based on the query text:

/anime?filter[text]=cowboy%20bebop

For more advanced search capabilities, consider using Algolia.

https://jsonapi.org/format/#fetching-filtering

You can choose how much of a resource to receive by specifying pagination parameters.

Pagination is supported via limit and offset. Resources are paginated in groups of 10 by default and can be increased to a maximum of 20 (some routes may increase the limit).

/anime?page[limit]=5&page[offset]=0

The response will include URLs for the first, next and last page of resources in the links object based on your request.

https://jsonapi.org/format/#fetching-pagination

Sorting by attributes is also supported. By default, sorts are applied in ascending order. You can request a descending order by prepending - to the parameter.

You can use a comma-delimited list to sort by multiple attributes.

/users?sort=-followersCount,-followingCount

https://jsonapi.org/format/#fetching-sorting

You can include related resources with include=[relationship]. You can also specify successive relationships using .. A comma-delimited list can be used to request multiple relationships.

/anime?include=categories,mediaRelationships.destination

Included resources are added to a top-level array and linked to from the resources' relationship:

{
  data: {
    id: '1',
    type: 'anime',
    attributes: { ... },
    relationships: {
      categories: {
        data: [
          { id: '155', type: 'categories' } // Link ID and Type to included array
        ]
      }
    }
  },
  included: [
    { id: '155', type: 'categories', attributes: { ... }, relationships: { ... } }
  ]
}

https://jsonapi.org/format/#fetching-includes

You can request a resource to only return a specific set of fields in its response. For example, to only receive a user's name and creation date:

/users?fields[users]=name,createdAt

https://jsonapi.org/format/#fetching-sparse-fieldsets

JSON:API has a great advantage in that since its standardised, API-agnostic tools can be made to abstract away the semantics of consuming and working with the data. It is recommended that you use a JSON:API client to implement the Kitsu API for this reason.

Many implementations in over 13 languages can be found on the JSON:API website.

Kitsu uses OAuth 2 for authentication. Authentication is not required for most public-facing GET endpoints.

It is advised to use an OAuth2 client for the language you're using, however it is not required.

NOTE: NSFW/R18 content (feed posts, media, categories etc.) are hidden for all unauthenticated requests and for accounts that have NSFW content disabled in their settings.

Request Headers

OAuth does not use the JSON:API headers, instead one of the following headers are required:

After registering your app, you will receieve a client ID and a client secret. The client ID is considered public information and is used to build login URLs or included in source code. The client secret must be kept confidential.

NOTE: Application registration has not yet been implemented. For now, client_id and client_secret can be omitted, provided as empty strings or with the following:

CLIENT_ID: dd031b32d2f56c990b1425efe6c42ad847e7fe3ab46bf1299f05ecd856bdb7dd
CLIENT_SECRET: 54d7307928f63414defd96399fc31ba847961ceaecef3a5fd93144e960c0e151

Password Grant

Send a POST request to https://kitsu.io/api/oauth/token with the following body:

application/json

{
  grant_type: 'password',
  username: '<email|slug>',
  password: '<password>' // RFC3986 URl encoded string
}

application/x-www-form-urlencoded

grant_type=password&username=<email|slug>&password=<password>

IMPORTANT: If you use x-www-form-urlencoded, you must URL encode the password field using the RFC3986 encoding scheme.

Send a POST request to https://kitsu.io/api/oauth/token with the following body:

NOTE: If the token was issued using a client_secret then the client_id and client_secret parameters must be provided.

application/json

{
  grant_type: 'refresh_token',
  refresh_token: '<refresh_token>'
}

application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>

Once you've obtained the access_token using one of the grant types, you can add the following header to all API requests:

Authorization: Bearer <access_token>

Successful Response

If the request for an access token is valid, the server will respond with the following data:

{
  access_token: 'abc123', // Token used in Authorization header
  created_at: 1518235801,
  expires_in: 2591963, // Seconds until the access_token expires (30 days default)
  refresh_token: '123abc', // Token used to get a new access_token
  scope: 'public',
  token_type: 'bearer'
}

Unsuccessful Response

If the access token request is invalid, the server will respond with one of six errors in the following format:

{
  error: 'invalid_request',
  error_description: '<reason_why>'
}

These six errors are:

Kitsu uses Algolia for searching. Algolia's search provides more accurate search results and allows you to build complex search filters to find exactly what you want. Refer to the Algolia Docs for further usage.

IMPORTANT:

• These keys are not static;
• These keys respect user content settings - Mature content will not be visible if:
  • The keys are requested without a valid Authorization header
  • The user associated with the Authorization header has mature content disabled in their settings.
• These keys are unique for each logged-in user and must not be shared.
  • Sharing keys requested with a valid Authorization header will leak blocked accounts, blocked media and private groups the user has joined.

Anime with an age rating of R18 requires a valid Authorization header and mature content enabled in the users' settings