Operate asynchronous jobs

ParseHawk extraction and parsing are asynchronous. Use the separate top-level collections /v1/extraction-jobs and /v1/parse-jobs; a fair worker services both queues.

Create and inspect extraction jobs

parsehawk extraction-jobs create receipt --file-id file_...
parsehawk extraction-jobs get job_...
parsehawk extraction-jobs list --extractor receipt

Use the one-shot helper when a shell script should upload and wait in one command:

parsehawk extract document.pdf \
  --extractor invoice_v1 \
  --wait \
  --timeout-seconds 900 \
  --output result.json

parsehawk jobs ... and /v1/jobs are deprecated v0.3 aliases for extraction jobs. They are removed in v0.4.

Create and inspect parse jobs

Upload a PDF or image, then select a parser by stable name or ID:

parsehawk parse-jobs create document-to-markdown --file-id file_...
parsehawk parse-jobs get parse_job_...
parsehawk parse-jobs list --parser document-to-markdown

For upload, submission, bounded polling, and Markdown output in one command:

parsehawk parse document.pdf \
  --parser document-to-markdown \
  --wait \
  --timeout-seconds 900 \
  --output document.md

Omit --parser to use document-to-markdown. Without --output, completed whole-document Markdown is written to stdout.

Handle lifecycle states

State	Meaning	Client action
queued	Accepted and waiting for a worker	Poll with backoff or cancel
running	A worker is extracting or parsing	Poll; do not submit a duplicate automatically
canceling	Cancellation requested while running	Wait for canceled
deleting	Deletion requested while running	Stop polling once the resource returns 404
completed	Workflow-specific result stored	Read extraction JSON or parsing Markdown
failed	Processing ended with an error	Inspect the error before deciding to retry
canceled	Work stopped without a result	Submit a new job if still needed

Cancel or delete

The REST API exposes a dedicated cancel operation. The CLI’s delete command applies the appropriate lifecycle behavior:

parsehawk extraction-jobs cancel job_...
parsehawk extraction-jobs delete job_...
parsehawk parse-jobs cancel parse_job_...
parsehawk parse-jobs delete parse_job_...

A queued or terminal job can be removed immediately. A running job first enters deleting while the worker observes the cancellation request.

A file, extractor, or parser referenced by a job cannot be deleted. Delete the job explicitly first, then delete its parent resources. This preserves every job ID that the API has returned until the client deliberately removes that job.

Retry deliberately

Job creation does not currently accept an idempotency key. To avoid duplicates:

1. Persist the returned job ID before polling.
2. On a network timeout, query the relevant job collection before submitting again.
3. Retry terminal failures only when the error is transient or the reusable definition has changed.
4. Put a client-side deadline around polling.

See errors and job states for the exact client contract.