Skip to main content
The Jobs API lets you create, monitor, cancel, and delete background crawl jobs. All endpoints are under /api/job and require authentication.
The list endpoint path is /api/jobs (the /job prefix + s suffix). Single-resource and action endpoints use /api/job/{id}.
Jobs are the primary way to trigger long-running operations such as fetching novel metadata, downloading chapter content, or generating e-book artifacts.

​
Job types

ValueDescription
0Fetch a single novel (NOVEL)
1Fetch multiple novels in a batch (NOVEL_BATCH)
5Full novel fetch including all content (FULL_NOVEL)
6Full novel fetch batch (FULL_NOVEL_BATCH)
10Fetch a single chapter (CHAPTER)
11Fetch chapters in a batch (CHAPTER_BATCH)
20Fetch a single volume (VOLUME)
21Fetch volumes in a batch (VOLUME_BATCH)
30Fetch a single image (IMAGE)
31Fetch images in a batch (IMAGE_BATCH)
40Generate a single artifact (ARTIFACT)
41Generate artifacts in a batch (ARTIFACT_BATCH)

​
Job statuses

ValueDescription
0PENDING — queued, not yet started
1RUNNING — currently executing
2SUCCESS — completed successfully
3FAILED — completed with an error
4CANCELED — stopped by a user or admin

​
Job priorities

ValueDescription
0LOW
1NORMAL
2HIGH

​
GET /api/jobs

Return a paginated list of jobs visible to the authenticated user. Query parameters
​
offset
integer
default:"0"
Number of records to skip.
​
limit
integer
default:"20"
Maximum records to return. Cannot exceed 100.
​
type
integer
Filter by job type (see table above).
​
status
integer
Filter by job status.
​
priority
integer
Filter by job priority.
​
user_id
string
Filter by the user who created the job.
​
parent_job_id
string
Filter by parent job ID (for child jobs in a batch).
​
is_done
boolean
Filter by completion state (true = finished, false = in progress).
Response — Paginated[Job]
​
total
integer
Total matching records.
​
offset
integer
Current offset.
​
limit
integer
Current limit.
​
items
Job[]
curl -s "http://localhost:8080/api/jobs?status=1" \
  -H "Authorization: Bearer $TOKEN"

​
GET /api/job/

Return details for a single job. Use this endpoint to poll job progress. Path parameters
​
job_id
string
required
The job’s unique ID.
Response — a Job object (same fields as the list response). 
curl -s http://localhost:8080/api/job/job001 \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "job001",
  "user_id": "a1b2c3",
  "parent_job_id": null,
  "depends_on": null,
  "type": 10,
  "priority": 0,
  "status": 1,
  "is_done": false,
  "is_running": true,
  "is_pending": false,
  "error": null,
  "done": 0,
  "failed": 0,
  "total": 1,
  "progress": 0,
  "job_title": "Overgeared · Chapter 42",
  "started_at": 1700001000000,
  "finished_at": null,
  "created_at": 1700000900000,
  "updated_at": 1700001000000,
  "extra": {}
}

​
POST /api/job//cancel

Cancel a running or pending job. Path parameters
​
job_id
string
required
The job’s unique ID.
Response — true on success. 
curl -s -X POST http://localhost:8080/api/job/job001/cancel \
  -H "Authorization: Bearer $TOKEN"

​
POST /api/job//replay

Create a new job with the same type and parameters as an existing job. Path parameters
​
job_id
string
required
The ID of the job to replay.
Response — the newly created Job object. 
curl -s -X POST http://localhost:8080/api/job/job001/replay \
  -H "Authorization: Bearer $TOKEN"

​
DELETE /api/job/

Delete a job record. Any running execution is stopped first. Path parameters
​
job_id
string
required
The job’s unique ID.
Response — true on success. 
curl -s -X DELETE http://localhost:8080/api/job/job001 \
  -H "Authorization: Bearer $TOKEN"

​
Creating jobs

​
POST /api/job/create/fetch-novel

Fetch (or refresh) novel metadata from its source URL. Set full to true to also enqueue chapter content downloads. Request body
​
url
string
required
The full URL of the novel’s main page on the source site.
​
full
boolean
default:"false"
When true, also fetches all chapter contents after the novel metadata is retrieved.
Response — a Job object. 
curl -s -X POST http://localhost:8080/api/job/create/fetch-novel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://readnovelfull.com/overgeared.html", "full": false}'

​
POST /api/job/create/fetch-volumes

Queue a job to download chapter contents for one or more volumes.
Providing a single volume ID creates a VOLUME job. Multiple IDs create a VOLUME_BATCH job.
Request body
​
volumes
string[]
required
List of volume IDs whose chapter contents should be fetched. Must contain at least one ID.
Response — a Job object. 
curl -s -X POST http://localhost:8080/api/job/create/fetch-volumes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"volumes": ["vol001", "vol002"]}'

​
POST /api/job/create/fetch-chapters

Queue a job to download content for specific chapters.
Providing a single chapter ID creates a CHAPTER job. Multiple IDs create a CHAPTER_BATCH job.
Request body
​
chapters
string[]
required
List of chapter IDs to fetch. Must contain at least one ID.
Response — a Job object. 
curl -s -X POST http://localhost:8080/api/job/create/fetch-chapters \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chapters": ["ch001", "ch002", "ch003"]}'

​
POST /api/job/create/fetch-images

Queue a job to download images for specific chapter image records. Request body
​
images
string[]
required
List of ChapterImage IDs to download. Must contain at least one ID.
Response — a Job object. 
curl -s -X POST http://localhost:8080/api/job/create/fetch-images \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"images": ["img001", "img002"]}'

​
POST /api/job/create/make-artifacts

Generate e-book artifacts for a novel in one or more output formats. The available formats depend on the user’s tier. Request body
​
novel_id
string
required
The ID of the novel to generate artifacts for.
​
formats
string[]
required
List of output format strings. Supported values: epub, json, txt, pdf, mobi, docx, rtf, fb2, azw3, lit, lrf, pdb, rb, tcr.
Response — a Job object (an ARTIFACT_BATCH job when multiple formats are requested). 
curl -s -X POST http://localhost:8080/api/job/create/make-artifacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"novel_id": "abc123", "formats": ["epub", "mobi"]}'

​
Typical workflow

# 1. Create a fetch-novel job
JOB_ID=$(curl -s -X POST http://localhost:8080/api/job/create/fetch-novel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://readnovelfull.com/overgeared.html"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 2. Poll until done
while true; do
  STATUS=$(curl -s http://localhost:8080/api/job/$JOB_ID \
    -H "Authorization: Bearer $TOKEN" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "Status: $STATUS"
  [ "$STATUS" -ge 2 ] && break
  sleep 2
done

# 3. Generate an EPUB artifact
curl -s -X POST http://localhost:8080/api/job/create/make-artifacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"novel_id\": \"$NOVEL_ID\", \"formats\": [\"epub\"]}"

Build docs developers (and LLMs) love

Get started for freeTalk to us