cURL walkthrough

Upload your own PDF and inspect every request from creation to download.

Prepare a small PDF named document.pdf. You will need Bash or Zsh, cURL 7.76 or later, Python 3, and jq. Conversion uses account credits.

Run the commands in order in the same terminal session. If a step fails, resolve the error before continuing.

Prepare authentication

Create a key in OOMOL Console, then set:

bash

export PDF_CRAFT_API_KEY="$(  python3 -c 'import getpass; print(getpass.getpass("API key: "))')"BASE=https://api.pdfcraft.ai/v1/pcc-api

The Python command reads the key without displaying it in the terminal. The remaining commands use cURL.

These API requests include your key, so they omit --location to avoid following redirects automatically. If you receive a redirect, check the request URL before continuing.

Create a task

bash

curl --fail-with-body --silent --show-error "$BASE/transforms" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  -H 'Content-Type: application/json' \  --data '{"input_format":"pdf","input_filename":"document.pdf"}' \  --output task.jsonTASK_UUID=$(jq -er '.uuid' task.json)

Expect HTTP 201 and status: "waiting_for_upload". Keep task.json; creation does not start processing. If the response is lost, investigate the waiting list rather than automatically creating another task.

Upload the file

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID/upload-urls" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  --output upload.jsonjq . upload.json

If put_url is present, send the file using all returned headers. For this PDF request the service currently returns Content-Type and x-oss-forbid-overwrite:

bash

curl --fail-with-body --silent --show-error \  --request PUT "$(jq -er '.put_url' upload.json)" \  -H "Content-Type: $(jq -er '.headers["Content-Type"]' upload.json)" \  -H "x-oss-forbid-overwrite: $(jq -er '.headers["x-oss-forbid-overwrite"]' upload.json)" \  --data-binary @document.pdf

Uploading the file does not require an API key. If the response contains get_url and head_url, the file has already been uploaded and you can continue to the next step.

Uploaded files cannot be overwritten. If the upload link expires before you use it, request a new one.

Start conversion

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID/launch" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  -H 'Content-Type: application/json' \  --data '{"output_format":"markdown"}'

The service returns 202 when it accepts the launch request. Repeating the same parameters returns 200 without running another conversion; changing them returns 409. For translation or EPUB output, see parameters.

Check status

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY"

While the status is running, wait before checking again. In your application, gradually increase the interval between requests and set an overall timeout, as in the Python example.

Stop polling when the status becomes succeeded, failed or cancelled. For failures, read error.code; calling launch again will not restart the task. To display processing progress, see progress and previews.

Download after success

Only after status becomes succeeded:

bash

curl --fail-with-body --silent --show-error \  "$BASE/transforms/$TASK_UUID/download-urls" \  -H "Authorization: Bearer $PDF_CRAFT_API_KEY" \  --output download.jsoncurl --fail --silent --show-error \  "$(jq -er '.get_url' download.json)" \  --output result.markdown.zip

Downloading the file does not require an API key. To inspect file information with a HEAD request, use head_url.

If the download link expires, you can request a new one. Once the task expires, the file is no longer available for download, so save your result in time.