One source, one hash
The filename changes. The hash of the bytes does not, until the bytes change. Use the hash to decide whether a new parse is required.
An idempotency key built from the source and the parsing options keeps a retry from creating a second job.
Structure the article, then embed
Help-center HTML and uploaded PDFs both need headings and sections before embedding. The chunk should say which heading it sits under.
Tables and procedures stay together. A step split across two chunks is retrieved as half a procedure.
Deletion is a separate action
Removing a source from the knowledge base means deactivating its chunks. Purge of the stored file is an authorized action with its own retention rule.
Do not treat a canceled job as proof the bytes are gone. Job status and retention are different fields.
What to store before the embedding
Hash the bytes. Build the idempotency key from that hash and the parsing options. A retry with the same key and the same body returns the existing job. The same key with a different body returns 409.
Embed only after warnings are acceptable. A digital PDF text-layer warning, a hidden-sheet warning, or an OCR fallback on one page changes whether that source is ready. Reparse when the hash or the options change. Reuse the DocIR when both match.
The container writes parserVersion cloudflare-docparse-container.0.2.0 on the document. Store that string with the source hash. Send a new Idempotency-Key when the bytes change. Reusing the old key with a different body returns 409 and the message Idempotency-Key was already used with a different request. Canceling a job leaves the stored source in place. Purge is the authorized action that tombstones the job and removes product-owned sources. A shared artifact is deleted only when no retained job still references it. Deactivate the knowledge-base chunks in the same change that removes the article from search. The trial cap remains 20 text-based documents, 200 MB per month, one active job, and a 20 MB upload. Stay inside that cap before you embed.
- One source hash, one parse, one set of chunks.
- Cite heading path plus pageIndex or sheet title.
- Deactivate chunks when the article is removed.
- Purge is a separate authorized action from canceling a job.
The file to send
Parse one help-center PDF before you embed it. Store the source hash, result.document, and parserVersion cloudflare-docparse-container.0.2.0 with the chunks.
Reuse the DocIR when the hash and the options match. A new body sent with the old Idempotency-Key returns HTTP 409, Idempotency-Key was already used with a different request. Deactivate the chunks in the same change that removes the article from search.
- Cancel leaves the stored source in place.
- Purge is the authorized action that tombstones the job.
- Stay inside 20 documents, 200 MB, one active job, and 20 MB per upload.
export DOCPARSE_URL="https://docparse.genedai.me"
export DOCPARSE_API_KEY="your_key"
curl -fsS -X POST \
"$DOCPARSE_URL/v1/parse?wait=true" \
-H "Authorization: Bearer $DOCPARSE_API_KEY" \
-F "file=@document.pdf" \
-F "mode=both" \
-o result.json
jq -r '.result.markdown' result.json
jq '.result.document.schemaVersion, .result.document.pages[0].blockIds' result.json
jq '.result.manifest.decision.route, .result.manifest.parserVersion' result.json
Frequently asked questions
Questions this guide answers
When should a knowledge-base article be reparsed?
Reparse when the source bytes or the parsing options change. Reuse the stored DocIR when the hash and the options match. An Idempotency-Key sent again with a different body returns 409.
What should each chunk cite?
Cite the source id, the heading path, and the location: PDF pageIndex, the Slide N heading, or the Sheet title. Include parserVersion so a later reader knows which parse produced the text.
Does deleting a job delete the file?
Canceling or deleting a job does not define retention. Purge is a separate authorized action. Deactivate the knowledge-base chunks when the article should disappear from search.