Skip to main content
Artifacts are the generated e-book output files produced after a make-artifacts job completes. All endpoints are under /api/artifact and require authentication.
The list endpoint path is /api/artifacts (the /artifact prefix + s suffix). Single-resource endpoints use /api/artifact/{id}.
To generate new artifacts, use POST /api/job/create/make-artifacts. To see all artifacts for a specific novel, use GET /api/novel/{novel_id}/artifacts.

​
Output formats

The following format strings are used across the Artifacts and Jobs APIs:
FormatDescription
epubEPUB e-book (native)
jsonJSON export
txtPlain text
pdfPDF document
mobiMobipocket (Kindle)
docxMicrosoft Word
rtfRich Text Format
fb2FictionBook 2
azw3Kindle Format 8
litMicrosoft LIT
lrfSony LRF
pdbPalm Database
rbRocket Book
tcrPsion/Epoc
Formats other than epub and json require Calibre to be installed on the server. The available formats for your account depend on your user tier.

​
GET /api/artifacts

Return a paginated list of artifacts. Authentication is required. Query parameters
​
offset
integer
default:"0"
Number of records to skip.
​
limit
integer
default:"20"
Maximum records to return. Cannot exceed 100.
​
novel_id
string
Filter by novel ID.
​
job_id
string
Filter by the job that generated the artifact.
​
user_id
string
Filter by the user who triggered artifact generation.
​
format
string
Filter by output format (e.g. epub, mobi).
Response — Paginated[Artifact]
​
total
integer
Total matching records.
​
offset
integer
Current offset.
​
limit
integer
Current limit.
​
items
Artifact[]
curl -s "http://localhost:8080/api/artifacts?novel_id=abc123" \
  -H "Authorization: Bearer $TOKEN"

{
  "total": 2,
  "offset": 0,
  "limit": 20,
  "items": [
    {
      "id": "art001",
      "novel_id": "abc123",
      "job_id": "job042",
      "user_id": "a1b2c3",
      "format": "epub",
      "file_name": "Overgeared.epub",
      "file_size": 4823091,
      "output_file": "novels/abc123/artifacts/Overgeared.epub",
      "is_available": true,
      "created_at": 1700002000000,
      "updated_at": 1700002000000
    }
  ]
}

​
GET /api/artifact/enabled-formats

Return the list of output formats that are enabled for the currently authenticated user. The available formats depend on the user’s tier. Response — array of format strings. 
curl -s http://localhost:8080/api/artifact/enabled-formats \
  -H "Authorization: Bearer $TOKEN"

["epub", "json", "txt"]

​
GET /api/artifact/

Return a single artifact record by its ID. Path parameters
​
artifact_id
string
required
The artifact’s unique ID.
Response — an Artifact object (same fields as items in the list response). 
curl -s http://localhost:8080/api/artifact/art001 \
  -H "Authorization: Bearer $TOKEN"

​
Downloading artifact files

Artifact files are served from the /static path using the output_file field as the path component: 
# Fetch the artifact record first
OUTPUT_FILE=$(curl -s http://localhost:8080/api/artifact/art001 \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['output_file'])")

# Download the file
curl -s -O "http://localhost:8080/static/$OUTPUT_FILE"
Static file serving requires authentication. Include the bearer token or use HTTP Basic Auth when downloading.

Build docs developers (and LLMs) love

Get started for freeTalk to us