The factory, for you or your AI agent
Your decisions stay in the browser. The repetitive part can run itself.
Most authors use the factory page and never need this one. If you work with an AI agent (Claude, ChatGPT, Cursor or your own scripts), it can take over the loop that eats an afternoon: upload the manuscript, read what Inspect finds, fix the file, upload it again, build a proof, download it. It does that with six ordinary web calls. Same pass, same outputs, nothing your browser couldn't do. The decisions stay yours.
Who does what
| You, on the factory page | The transmittal: title page, copyright page, page size, typography, and what your own styles mean. Marking it final. Deciding when a proof is good enough to spend a final on. |
| Your agent, over the API | Upload, Inspect, fix the file, upload again, as many times as it takes. Proofs and downloads. Inspect and proofs are free. |
| The studio | The house typography, the rules Inspect checks, and help when you're stuck: jenna@jdbb.net. |
Hand this to your agent
You need two things from the studio, both in the message that came with your API token: your project id (a number) and your token (it starts fk_). Treat the token like a password. Your agent needs it; nobody else does, so keep it out of shared documents.
Then give your agent something like this, with your id and token filled in:
Help me get my book through the [jdbb] studio factory. Base URL: https://studio.jdbb.net Project id: <your project id> Token: <your token> (send it as the header Authorization: Bearer <token>) How the API works: https://studio.jdbb.net/factory/api Help pages, as plain text for agents: https://studio.jdbb.net/help/llms.txt Work in this loop: 1. Upload my manuscript (.docx). 2. Run Inspect, then read every finding: GET /api/projects/<id>/preflight?book_id=<book>&findings=1 3. Fix what you can in the .docx: paragraph styles and [[markers]]. Never change my words without asking me first. 4. Upload the fixed file and inspect again, until nothing you can fix is left under "worth fixing". 5. Build a proof (free), download the PDF and EPUB, and tell me what you changed and what's left for me to decide. Ask me before you build a final (it uses one of my finals), change any of my text, or touch my transmittal.
An agent that reads the web can work from this page alone: everything it needs is under The six calls. Any help page is also available as Markdown by adding .md to its address.
Prefer a terminal yourself?
factory.py runs the same factory as plain commands, from a folder on your own computer. Nothing to install: it needs only Python 3, which every Mac already has.
curl -sO https://studio.jdbb.net/factory/api/factory.py python3 factory.py setup # once: your project id and token, checked and saved in this folder python3 factory.py inspect manuscript.docx # free: what the factory sees; the report opens in your browser python3 factory.py proof manuscript.docx # free: PDF (with a PROOF line) and EPUB in ./out python3 factory.py final manuscript.docx # uses one final: the clean PDF for your printer, and the EPUB
The six calls — the reference for agents and developers
0. What you need
| Thing | Where it comes from |
|---|---|
| Base URL | https://studio.jdbb.net |
| Project id | A number, in the message that came with your token (“Your project id is …”). Lost it? GET /api/clients/{client}/projects lists your projects with their ids; {client} is the first part of your factory page's address. |
| Token | Your project's API token (starts fk_; the studio issues it and shows it once) or the project password the factory page asks for. Prefer the API token: the studio can replace it without changing your password. Ask if you don't have one. |
| A live pass | Upload, inspect and build all return 403 {"error":"this project has no factory pass"} without one. See the factory page. |
Send the token on every call, any of three equivalent ways:
Authorization: Bearer <token> # what most HTTP tooling has a switch for X-Auth-Token: <token> Cookie: prodcal_auth_<project id>=<token> # what the browser uses
A wrong or missing token is 401 {"error":"unauthorized"} on every route. The examples below assume:
B=https://studio.jdbb.net
P=14 # your project id
H="Authorization: Bearer $TOKEN"
1. Check the pass — free
curl -s -H "$H" $B/api/projects/$P/pass
{"exists":true,"status":"active","live":true,"builds_included":3,"builds_extra":0,
"builds_used":1,"credits_remaining":2,"expires_at":"2027-03-19T12:41:46Z","customer_name":"…"}
2. Upload the manuscript — free
Multipart; fields file, title, author, project_id, all four required (400 {"error":"title and author required"} otherwise). Each upload is a new book on the project; it doesn't overwrite the last one, and the newest is the one the factory page shows as current. A file named .docx that isn't a Word document inside is refused with 400.
BOOK=$(curl -s -H "$H" -F file=@manuscript.docx -F title='My Book' -F author='Me' \
-F project_id=$P $B/api/books/upload | jq .id)
201 {"author":"Me","id":26,"status":"uploaded","title":"My Book"}
3. Inspect — free, unlimited
POST runs it. GET …?book_id= re-reads the latest; add &findings=1 for every finding, which is what an agent should read. The report a person reads is at report_url.
curl -s -H "$H" -X POST $B/api/projects/$P/preflight \
-H 'Content-Type: application/json' -d "{\"book_id\":$BOOK}" | jq .summary
curl -s -H "$H" "$B/api/projects/$P/preflight?book_id=$BOOK&findings=1" \
| jq '.findings[] | select(.severity != "low") | {severity, type, style_name, location, suggestion}'
The JSON is {exists, project_id, book_id, status: ready|error, source_filename, updated_at, summary:{total, high, medium, low, preserved, by_type:{…}}, book_map:{sections:[{title, kind, paras, words}], warnings, notes, summary}, report_url, history:[…]}, plus findings:[{type, severity, location, text, style_name, suggestion, …}] with findings=1. Severity high is what the factory page calls worth fixing, medium worth a look; low rows are notes. Each suggestion says what to do in plain words.
4. Build — proofs free, finals one credit
kind is "proof" (the default when omitted: free, up to 30 a day per project, a PROOF line on every page of the PDF) or "final" (one credit, clean PDF, the delivery email; an agent should ask the author first). format is "both" (default: print PDF + EPUB), "pdf" or "epub"; an EPUB-only build is always a free proof. Optional callback_url (public https): the server POSTs the status JSON from step 5 there once, when the build ends. Optional "index": true sets the book’s reviewed back-of-book index at the back of the print PDF; it needs the Index add-on on the pass (else 402 with "addon":"index") and a draft to include (400 until POST /api/books/{id}/index/draft has run; GET /api/books/{id}/index shows its status and entries, PUT saves your edits).
curl -s -H "$H" -X POST $B/api/books/$BOOK/convert \
-H 'Content-Type: application/json' -d '{"format":"both","kind":"proof"}'
200 {"book_id":26,"format":"both","kind":"proof","status":"converting","status_url":"/api/books/26"}
402 {"error":"no finals remaining","credits_remaining":0}
429 {"error":"proof limit reached: 30 proofs in the last 24 hours for this project; try again later"}
409 {"error":"a build is already running for this project; wait for it to finish"}
For a final, the credit is taken when convert is accepted; a final that fails gives it back automatically. Proofs touch no credit. Inspect, upload, status and downloads are free. A final transmittal saved since the last build is applied at convert time, so you don't need the Word template first.
5. Wait for the build
until curl -s -H "$H" $B/api/books/$BOOK | jq -e '.status=="ready" or .status=="error"' >/dev/null; do sleep 3; done curl -s -H "$H" $B/api/books/$BOOK | jq .
Success: a short book takes a few seconds, a 110-page book about 30.
{"book_id":26,"project_id":14,"title":"My Book","author":"Me","source_filename":"manuscript.docx",
"status":"ready","updated_at":"2026-09-19T12:42:33Z",
"outputs":[{"id":73,"format":"epub","kind":"proof","size_bytes":5927,"download_url":"/api/books/26/outputs/73/download"},
{"id":72,"format":"pdf","kind":"proof","size_bytes":38954,"download_url":"/api/books/26/outputs/72/download"}]}
Failure: status is "error", outputs is empty, and error is the same text the factory page shows. It starts with a plain explanation and what to do. When the fault is in the author's text, a Near: “…” line quotes the paragraph so it can be found in the manuscript. When the fault is in the studio's own setup, the text says so, and there's nothing to change in the manuscript. A Technical detail: line may follow.
{"book_id":27,"status":"error","outputs":[],
"error":"We couldn't read this .docx. Save or export it again from your editor as a .docx (Google Docs: File → Download → .docx; …) and try again. …\nTechnical detail: pandoc typst: exit status 63"}
Statuses you will see: uploaded → converting → ready | error.
6. Download
By format (the latest output of that format) or by the download_url from the status JSON (one specific output). Both set Content-Disposition with a dated filename.
curl -s -H "$H" -o book.pdf $B/api/books/$BOOK/download/pdf # application/pdf curl -s -H "$H" -o book.epub $B/api/books/$BOOK/download/epub # application/epub+zip curl -s -H "$H" -o final.pdf $B/api/books/$BOOK/download/pdf?kind=final # newest of a kind: ?kind=final|proof curl -s -H "$H" -o out.pdf $B/api/books/$BOOK/outputs/72/download
The whole thing, one screen
B=https://studio.jdbb.net; P=14; H="Authorization: Bearer $TOKEN"
BOOK=$(curl -s -H "$H" -F file=@ms.docx -F title='My Book' -F author='Me' -F project_id=$P $B/api/books/upload | jq .id)
curl -s -H "$H" -X POST $B/api/projects/$P/preflight -H 'Content-Type: application/json' -d "{\"book_id\":$BOOK}" | jq .summary
curl -s -H "$H" -X POST $B/api/books/$BOOK/convert -H 'Content-Type: application/json' -d '{"format":"both","kind":"proof"}'
until curl -s -H "$H" $B/api/books/$BOOK | jq -e '.status!="converting" and .status!="uploaded"' >/dev/null; do sleep 3; done
curl -s -H "$H" $B/api/books/$BOOK | jq -r '.error // "ok"'
curl -s -H "$H" -o book.pdf $B/api/books/$BOOK/download/pdf; curl -s -H "$H" -o book.epub $B/api/books/$BOOK/download/epub
Python, stdlib only
factory-cli.py is the six calls as a short script with no dependencies, for your own tooling; the Factory class at the top is the part you'd keep. For running a book by hand, factory.py is friendlier.
curl -sO https://studio.jdbb.net/factory/api/factory-cli.py export FACTORY_TOKEN=… python3 factory-cli.py --project $P inspect ms.docx # a short summary python3 factory-cli.py --project $P inspect ms.docx --json # the full report, every finding python3 factory-cli.py --project $P build ms.docx --out ./out
inspect = upload → Inspect (free) → a summary of what's worth fixing and a link to the full report (--json: the report with every finding). build = upload → build (--kind proof by default, free; --kind final one credit) → wait → download both files into --out.
Also callable — not needed for a build
GET/PUT /api/projects/{id}/transmittal: read or fill the transmittal as JSON,{"status":"final","data":{…}}; a final one is applied at the next build. An agent can read it, or draft answers for you to check on the factory page. Leave marking it final to the author.GET /api/projects/{id}/word-template: the styled .docx template (409until the transmittal is final).GET /api/projects/{id}/books: every book on the project (ids, statuses).GET /api/books/{id}/outputs: all output files for a book.
Not available with a token: ask the studio
- Creating or replacing the token.
- Changing the book's production settings directly; the transmittal is your side of them.
- Buying finals; deleting books.
Errors, in one table
| Status | Means |
|---|---|
| 401 | Token missing or wrong. |
| 402 | No finals left on the pass (credits_remaining is in the body), or "index": true without the Index add-on ("addon":"index"). |
| 403 | The project has no live Factory Pass. |
| 400 | A required field is missing (title, author, book_id…), or the upload isn't a Word document. The body says which. |
| 409 | A build is already running on this project, or the transmittal isn't final yet (template). |
| 429 | Too many proofs today (30 per project per day). |
200 + "status":"error" | The build itself failed. A final's credit comes back; read error. |