API Documentation

Last Updated on October, 17, 2025

This guide outlines the three-step process to upload a PDF, trigger its processing, and receive the results using our REST API. To simplify this workflow, you can use the provided Python client directly from your terminal:

python call-chunkify-api.py \
  ./input/old_school_file.pdf \
  --api-key <YOUR_API_KEY
Download the script

Use flags to control where to write the output and where to store the content on the chunkify platform. To see the options run python call-chunkify-api.py -h .

To get access to the API, contact hello@chunkify.io

Step 1: Get a Secure Upload URL

First, you must inform the API that you intend to upload a file. The API will respond with a unique Document ID (docID) and a pre-signed URL where you can upload the file's content.

  • Method: POST

  • Endpoint: /api/v1/upload

Request
curl -X POST 'https://app.chunkify.io/api/v1/upload' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "file": "example-document.pdf",
    "type": "application/pdf",
    "chunkifyPath": "path/to/your/doc"
  }'
Parameters in the JSON Body:

  • file (string, required): The name of the file you intend to upload.

    • Note: Similar to a PC file system, only one document of a certain name can exist in the same folder on the chunkify cloud.

  • type (string, required): The MIME type of the file. Currently, this should be application/pdf.

  • chunkifyPath (string, optional): A string representing the virtual directory path to store the file (e.g., path/to/your/doc). Leading or trailing slashes are ignored. If this parameter is omitted, the file will be placed in your root directory.

Response

  • Success response (200 OK): You will need to save the docID and uploadURL from the response for the next steps.

{
  "uploadURL": "https://storage.googleapis.com/...", // Pre-signed URL 
  "docID": "unique-document-identifier" // Document ID for processing
}

  • Error responses: Check "message" in the response for details

Step 2: Upload the File Content

Next, upload the binary data of your PDF file to the pre-signed uploadURL you received in Step 1.

  • Method: PUT

  • Endpoint: The dynamic uploadURL from the previous step's response.

Request

This request does not require an Authorization header, as authentication is handled by the pre-signed URL. You must, however, specify the Content-Type and send the file's raw data as the body.

curl -X PUT '<THE_UPLOAD_URL_FROM_STEP_1>' \
  -H 'Content-Type: application/pdf' \
  --data-binary '@/path/to/your/local/example-document.pdf'
Response

Response

  • Success response (200 OK): No JSON response body

  • Error responses: This step uses Google Cloud Storage's pre-signed URL mechanism. Error responses follow Google Cloud Storage conventions.

Step 3: Start the Processing Job

Finally, after the file has been successfully uploaded, you can instruct the API to begin processing it.

  • Method: POST

  • Endpoint: /api/v1/process

Request

This request requires your API key for authorization and a JSON body containing the docID you received in Step 1.

curl -X POST 'https://app.chunkify.io/api/v1/process' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "docID": "<THE_DOC_ID_FROM_STEP_1>"
  }'
Response

Response

  • Success response (200 OK): Upon a successful request, the API will respond directly with the ZIP archive containing your processing result. Currently this defaults to DITA.

    • Response Body: The raw binary data of the .zip file.

    • Headers:

      • Content-Type: application/zip

      • Content-Disposition: attachment; filename="{docID}.zip" - This suggests a filename for the download.

      • X-Page-Count: <numPages> - A custom header containing the number of pages in the document for billing purposes.

  • Error responses: Check "message" in the response for details

Saving the response file

Using curl, you can do this easily with the —output flag.

curl -X POST 'https://app.chunkify.io/api/v1/process' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{"docID": "<THE_DOC_ID_FROM_STEP_1>"}' \
--output <YOUR_FILE_NAME>.zip