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: {}