NoviList Public API v1

An interactive schema explorer is available at https://api.novilist.co/api/v1/explorer. Use it to browse types, run test queries, and inspect the full public schema.

Low-volume catalog queries and introspection can be tried without credentials. Use an application key for an attributable catalog quota, or OAuth when acting for a user.

POST /api/v1/graphql HTTP/1.1
Host: api.novilist.co
Content-Type: application/json
X-Application-Key: nvl_app_...

Authorization: Bearer nvl_usr_...

Before using the API, register an application in developer settings. Registration is immediate and returns:

You may register up to 20 applications. Key rotation invalidates the previous key. Disabling or deleting an application invalidates all associated user tokens.

NoviList uses OAuth 2.0 with mandatory PKCE S256. There are no client secrets or refresh tokens. Tokens are valid for one year.

// Generate PKCE values
function generatePKCE() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  const verifier = btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

  return crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
    .then(buf => {
      const challenge = btoa(String.fromCharCode(...new Uint8Array(buf)))
        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
      return { verifier, challenge };
    });
}

https://api.novilist.co/api/v1/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=user%3Aread+readinglist%3Aread
  &state=RANDOM_STATE
  &code_challenge=YOUR_CHALLENGE
  &code_challenge_method=S256

POST /api/v1/oauth/token HTTP/1.1
Host: api.novilist.co
Content-Type: application/x-www-form-urlencoded

code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&redirect_uri=https://yourapp.com/callback
&code_verifier=YOUR_VERIFIER

{
  "access_token": "nvl_usr_...",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "scope": "user:read readinglist:read"
}

Scopes control what operations a bearer token can perform. Request only the scopes you need. Scopes do not imply one another.

Catalog-only requests using an application key do not require OAuth. Add user-specific scopes via bearer token when needed.

The public catalog includes novels with titles, covers, release dates, staff credits, publishers, tags, genres, relations, and public external links. Disabled links and internal notes are excluded.

query SearchNovels($query: String!, $first: Int, $after: String) {
  searchNovels(query: $query, first: $first, after: $after) {
    nodes {
      id
      title { english romanized native }
      coverImage { medium }
      status
      tags { id name category }
      novelStaff { role staff { id name { full native } } }
      novelPublishers { isOfficial publisher { id name } }
      externalLinks { platform url purpose language }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

query StaffAndPublisher($staffId: ID!, $publisherId: ID!) {
  staff(id: $staffId) {
    id
    name { full native }
    externalLinks { platform url }
  }
  publisher(id: $publisherId) {
    id
    name
    publisherType
    externalLinks { platform url }
  }
  genreCollection { genre count }
}

List queries use cursor-based pagination. This is more efficient than offset-based pagination for large datasets and provides consistent results when items are inserted or deleted between requests.

To fetch the next page, take the endCursor from the previous response and pass it as the after argument. Stop when hasNextPage is false.

query SearchNovels($query: String!, $after: String) {
  searchNovels(query: $query, first: 20, after: $after) {
    nodes {
      id
      title { english romanized }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

# First page: omit 'after'
# Variables: { "query": "mushoku" }

# Second page: use endCursor from first response
# Variables: { "query": "mushoku", "after": "cursor_abc123" }

The searchNovels query accepts optional filter arguments to narrow results. All filters are combinable.

query FilteredSearch {
  searchNovels(
    query: "mushoku"
    status: [ONGOING]
    genres: ["Fantasy"]
    first: 10
  ) {
    nodes {
      id
      title { english romanized }
      status
      tags { name category }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Other filters include excludedTags, excludedGenres, isAdult, isLicensed, completelyTranslated, and year. Consult introspection for exact argument types instead of hard-coding a copied schema.

Authenticated users can read their reading lists and update progress. The public API uses cursor pagination with after and first arguments.

query MyReadingList {
  readingListCollection {
    lists {
      name
      status
      count
      entries(first: 25) {
        nodes {
          id
          status
          progress
          score
          novel {
            id
            title { english romanized }
          }
        }
        pageInfo { hasNextPage endCursor }
        totalCount
      }
    }
  }
}

mutation UpdateProgress($novelId: ID!, $progress: Int!) {
  saveReadingListEntry(novelId: $novelId, progress: $progress) {
    id
    status
    progress
    updatedAt
  }
}

Without userId or userName, the query targets the authenticated user. Another user's public list may be requested explicitly; private entries remain filtered.

The public API can look up likely catalog matches, read the authenticated user's submission history, and create new-novel or existing-novel edit proposals.

query MySubmissions($after: Cursor) {
  mySubmissions(after: $after, first: 25) {
    nodes {
      id
      kind
      status
      displayName
      rejectionReason
      liveEntityId
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

mutation CreateNovelSubmission($input: CreateNovelSubmissionInput!) {
  createNovelSubmission(input: $input) {
    id
    submissionStatus
    isNewNovel
    requiresReview
  }
}

Use submissions:read for history and submissions:write for creation. Reuse a client-generated idempotencyKey when retrying the same attempt and set autoSubmit: true to enter the normal review pipeline. Use catalog:lookup for submissionEntityLookup. Submission notes are user-supplied content; do not render them as trusted HTML.

Executed operations follow the standard GraphQL format: a data key for successful operations, or an errors array when something goes wrong. Authentication failures that occur before GraphQL execution may instead be an HTTP JSON response containing top-level error and code fields.

{
  "data": {
    "searchNovels": {
      "nodes": [...],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "cursor_abc123"
      },
      "totalCount": 42
    }
  }
}

{
  "errors": [{
    "message": "Invalid application key",
    "extensions": {
      "code": "INVALID_APPLICATION_KEY"
    }
  }]
}

Authorization and validation error codes:

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1718430060

{"data": { ... }}

These are current defaults and may change. Treat the response headers as authoritative. GraphQL complexity limits are enforced separately from request quotas.

The API is versioned via the URL path: /api/v1/graphql. Introspection reports only the public v1 schema.

Developer application management uses the session-authenticated site schema, not public credentials.

Account security, application management, social features, moderation, administration, maintenance, chapter ingestion, and submission writes are not part of public API v1.