Skip to main content
The Lightnovel Crawler REST API is a FastAPI-based HTTP API that exposes the full functionality of the crawler: browsing novels, triggering crawl jobs, managing artifacts, and more.

​
Base URL

http://localhost:8080/api
All endpoint paths documented here are relative to this base URL.

​
Starting the server

lncrawl server
The server starts on port 8080 by default.

​
Authentication

The API uses JWT bearer tokens. Every protected endpoint requires an Authorization header: 
Authorization: Bearer <token>
The server also accepts HTTP Basic Auth (username/password) on every endpoint that accepts bearer tokens.

​
Default credentials

FieldValue
Emailadmin
Passwordadmin
Change the default password before exposing the server to any network.

​
Obtaining a token

Send a POST /api/auth/login request with your credentials. The response contains a token field you use in all subsequent requests. 
curl -s -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin", "password": "admin"}'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "a1b2c3d4",
    "email": "admin",
    "name": null,
    "role": "admin",
    "tier": 0,
    "is_active": true,
    "is_verified": false
  }
}
Use the token in subsequent requests: 
curl -s http://localhost:8080/api/novels \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Error responses

All errors follow a consistent JSON shape: 
{
  "detail": "A human-readable error message"
}
Validation errors (HTTP 422) include a more detailed breakdown: 
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Common HTTP status codes

CodeMeaning
200Success
400Bad request — invalid parameters or business rule violation
401Unauthorized — missing or invalid credentials
403Forbidden — authenticated but insufficient permissions
404Not found — the requested resource does not exist
422Unprocessable entity — request body failed schema validation
500Internal server error

​
Pagination

List endpoints return a Paginated wrapper object: 
{
  "total": 120,
  "offset": 0,
  "limit": 20,
  "items": []
}
Use offset and limit query parameters to page through results. The maximum limit is 100.

​
API sections

Authentication

Login, signup, token management, and password reset.

Novels

Browse and manage the novel library.

Chapters

Fetch chapter metadata and read chapter content.

Jobs

Create and monitor crawl jobs.

Artifacts

List and download generated e-book files.

Build docs developers (and LLMs) love

Get started for freeTalk to us