Put two PDFs beside your terminal

Choose two small PDFs and name them first.pdf and second.pdf. Put them in the folder your terminal is currently using, and have your LongRun API key ready.

We’re choosing Merge PDFs for this lesson. You’ll use the same upload pattern with other file actions, but each action’s input names can differ.

1. Upload the first document

Replace API_KEY and run the command below. The @./first.pdf part tells cURL to read the file from your current folder.

The response gives you a file id. This identifies the uploaded document; it is different from a run id, which identifies processing work. Copy your file id and keep it ready for step 3.

curl --fail-with-body "https://api.uselongrun.app/v1/files" \
  --header "Authorization: Bearer ${API_KEY}" \
  --form "file=@./first.pdf"

{
  "id": "file_first",
  "name": "first.pdf",
  "mime_type": "application/pdf"
}

2. Upload the second document

Now run the same kind of request for second.pdf. Keep this returned file id too. We’ll use the two IDs together in the next request.

You don’t need to add a Content-Type header here. With --form, cURL prepares the upload format for you.

curl --fail-with-body "https://api.uselongrun.app/v1/files" \
  --header "Authorization: Bearer ${API_KEY}" \
  --form "file=@./second.pdf"

3. Tell LongRun which order to use

Replace FIRST_FILE_ID and SECOND_FILE_ID below with your actual upload IDs. The order matters: the first item’s pages will come before the second item’s pages.

Run the request. We’ve finished uploading and are now asking for processing, so this response contains a run id. Copy it so we can follow the merge to completion.

curl --request POST "https://api.uselongrun.app/v1/pdf/merge" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --arg FIRST_FILE_ID "${FIRST_FILE_ID}" --arg SECOND_FILE_ID "${SECOND_FILE_ID}" '{
  "inputs": {
    "files": [
      $FIRST_FILE_ID,
      $SECOND_FILE_ID
    ]
  }
}')"

{
  "id": "run_example",
  "status": "queued",
  "outputs": null,
  "error": null
}

4. Wait for the result

Now let’s ask about the work we just submitted. Replace RUN_ID below with the real run id you copied, then run the command.

Look at status in the response. queued means it is waiting; running means it is being processed. Wait 2 seconds before checking again. When you see completed, you can move to the download. If you see failed or cancelled, stop and inspect the error instead.

For this exercise, stop checking after 2 minutes. That does not cancel the work—you can return to Runs to check it later.

curl --request GET "https://api.uselongrun.app/v1/runs/${RUN_ID}" \
  --header "Authorization: Bearer ${API_KEY}"

5. Download and check the file

Once status is completed, look inside outputs.file for the file id. We used the run id to check the work; now we need the file id to retrieve what it produced.

Replace FILE_ID with that id and run the download command. It saves the LongRun file as result.pdf in your current folder. Open it and check the content. You’ve now followed a request all the way from input to a usable file. The response example below shows only the fields we need for this step.

{
  "id": "run_example",
  "status": "completed",
  "outputs": {
    "file": {
      "id": "file_result",
      "name": "result.pdf",
      "mime_type": "application/pdf"
    }
  },
  "error": null
}

curl --fail-with-body "https://api.uselongrun.app/v1/files/${FILE_ID}/content" \
  --header "Authorization: Bearer ${API_KEY}" \
  --output result.pdf

If something goes wrong

If the request returns 401, check the API key. If the run fails, read error.message and open its details in Runs. Correct the input before submitting another run. A 202 response means accepted, not finished.

Keep a file for later

Temporary files have an expires_at timestamp. To keep an eligible file, use the save endpoint before it expires. Storage limits still apply.

curl --request POST "https://api.uselongrun.app/v1/files/${FILE_ID}/save" \
  --header "Authorization: Bearer ${API_KEY}"

Use a direct URL instead of uploading

For an accessible HTTP(S) file URL, you can pass the URL as a file input. It must lead to the file bytes, not a sharing page. Base64 and data URLs are not accepted.

{
  "inputs": {
    "files": [
      "https://example.com/first.pdf",
      "https://example.com/second.pdf"
    ]
  }
}

Understand result URLs

Returned file metadata includes a url and access/expiry information. For a signed URL, download it without your LongRun Authorization header. For LongRun’s /v1/files/{id}/content endpoint, include the key as shown above. If a signed URL expires while the file still exists, fetch the file metadata again.