OpenAPI Specification
openapi: 3.0.3
info:
title: AniList API v2 GraphQL API
version: 2.0.0
description: 'HTTP surface of the AniList API v2. The primary developer interface is a single GraphQL endpoint at https://graphql.anilist.co. OAuth2 authentication uses the Authorization Code and Implicit grant flows at https://anilist.co. This OpenAPI document captures the HTTP layer: the GraphQL POST endpoint, the OAuth2 authorize endpoint, the token exchange endpoint, and the auth pin redirect. The full GraphQL schema is profiled separately in `graphql/anilist-schema.graphql` (SDL) and `graphql/anilist-introspection.json` (introspection).'
termsOfService: https://docs.anilist.co/guide/terms-of-use
contact:
name: AniList Support
email: contact@anilist.co
url: https://docs.anilist.co/
license:
name: AniList Terms of Use (free for non-commercial / commercial < $150/mo)
url: https://docs.anilist.co/guide/terms-of-use
x-generated-from: documentation
x-last-validated: '2026-05-30'
x-api-evangelist-profile: https://github.com/api-evangelist/anilist
servers:
- url: https://graphql.anilist.co
description: AniList GraphQL endpoint (v2)
- url: https://anilist.co
description: AniList OAuth2 authorization server
security:
- {}
- bearerAuth: []
tags:
- name: GraphQL
description: GraphQL query and mutation endpoint
paths:
/:
post:
operationId: executeGraphQL
summary: Execute a GraphQL query or mutation
description: Execute a GraphQL query or mutation against the AniList schema. The request body must include a `query` string and may include a `variables` object and an `operationName`. Queries may be made anonymously; mutations require a Bearer access token obtained via OAuth2.
tags:
- GraphQL
servers:
- url: https://graphql.anilist.co
security:
- {}
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLRequest'
examples:
mediaById:
summary: Fetch a Media by ID
value:
query: 'query ($id: Int) { Media(id: $id) { id title { romaji english native } episodes status } }
'
variables:
id: 15125
searchMedia:
summary: Search media by title
value:
query: "query ($search: String, $page: Int, $perPage: Int) {\n Page(page: $page, perPage: $perPage) {\n pageInfo { currentPage lastPage hasNextPage total }\n media(search: $search, type: ANIME) { id title { romaji english } averageScore }\n }\n}\n"
variables:
search: Cowboy Bebop
page: 1
perPage: 10
responses:
'200':
description: A successful GraphQL response (may still contain an `errors` array)
headers:
X-RateLimit-Limit:
description: Per-IP/user request budget per minute (90, currently degraded to 30)
schema:
type: integer
X-RateLimit-Remaining:
description: Remaining requests in the current rate-limit window
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
examples:
ExecuteGraphQL200Example:
summary: Default executeGraphQL 200 response
x-microcks-default: true
value:
data:
Media:
id: 15125
title:
romaji: Teekyuu
english: Teekyuu
native: てーきゅう
episodes: 12
status: FINISHED
'400':
description: Malformed GraphQL document
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
'401':
description: Missing or invalid access token for a mutation requiring auth
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
'403':
description: API temporarily disabled or IP blocked
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
'429':
description: Rate limit exceeded; one-minute timeout applied
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
X-RateLimit-Limit:
schema:
type: integer
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp of next allowed request
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
examples:
ExecuteGraphQL429Example:
summary: Default executeGraphQL 429 response
x-microcks-default: true
value:
data: null
errors:
- message: Too Many Requests.
status: 429
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
GraphQLResponse:
title: GraphQLResponse
type: object
properties:
data:
type: object
nullable: true
additionalProperties: true
description: Selection result tree shaped like the requested query
errors:
type: array
description: Array of GraphQL errors when the request was not fully successful
items:
$ref: '#/components/schemas/GraphQLError'
extensions:
type: object
additionalProperties: true
GraphQLRequest:
title: GraphQLRequest
type: object
required:
- query
properties:
query:
type: string
description: GraphQL query or mutation document
example: query { Viewer { id name } }
variables:
type: object
additionalProperties: true
description: Map of variable values referenced in the query
operationName:
type: string
description: Name of the operation to execute when the document contains multiple
GraphQLError:
title: GraphQLError
type: object
properties:
message:
type: string
example: Too Many Requests.
status:
type: integer
example: 429
locations:
type: array
items:
type: object
properties:
line:
type: integer
column:
type: integer
path:
type: array
items:
oneOf:
- type: string
- type: integer
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth2 access token issued by AniList. No scopes; access tokens grant (almost) full access to a user's data. Tokens are valid for one year.
oauth2:
type: oauth2
description: AniList OAuth2 (no scopes supported)
flows:
authorizationCode:
authorizationUrl: https://anilist.co/api/v2/oauth/authorize
tokenUrl: https://anilist.co/api/v2/oauth/token
scopes: {}
implicit:
authorizationUrl: https://anilist.co/api/v2/oauth/authorize
scopes: {}