Skavio Agent Tools: handling PDF split and merge jobs in an API workflow
[Skavio Agent Tools](https://getskavio.com/agent-tools/) advertises PDF splitting and merging for company-authenticated, asynchronous jobs. A reliable integration needs more than a successful submission: define the intended pages, preserve the request identity through retries, retrieve the results securely and inspect the finished documents before releasing them downstream.
1. Define the document you want—not just the operation
Start with a written page plan. For a split, identify the source PDF and the pages the recipient should receive. For a merge, list the source documents and the intended final sequence. Keep the originals unchanged. Use fictional, visibly numbered PDFs for the first acceptance test. For example, prepare a three-page document labelled A1–A3 and a two-page document labelled B1–B2. Your intended merged result might be A1, A2, A3, B1, B2. That sequence is your acceptance criterion—not a verified promise about how the service interprets input order. In the research check dated 31 October 2026, the public catalogue marked pdf_split and pdf_merge available, and the published OpenAPI document listed both operation identifiers. This establishes advertised availability, not successful execution of an authenticated job. Some details still need confirmation before deployment.
- For splitting, confirm page-number origin, individual-page versus range syntax, ordering, duplicates and out-of-range handling. Do not assume the documented [1,3] example resolves these questions.
- For merging, confirm input-order behavior with the numbered fixtures.
- Confirm split output packaging; do not assume one file per page or ZIP delivery.
2. Submit from your server with a company-scoped key
The documented submission route is POST /agent-tools/api/jobs. Requests use Authorization: Bearer <secret> and an envelope containing tool, idempotency_key and arguments. Keys are company-scoped, revocable and displayed once when issued. Keep the secret in server-side configuration, not browser code, document metadata or application logs. For pdf_split, the documented arguments are data_base64 and pages. For pdf_merge, inputs_base64 contains two to five PDFs. Encode the approved source files, then construct the request using the current documented contract after resolving the selection and ordering questions above. These request details are documentation-based, not an end-to-end-tested example. The research identified legacy-domain base URLs in the published documentation. The paths shown here are therefore not complete executable requests: confirm the canonical authenticated API host before deploying a client.
- Authorize access to every source document before submission.
- Apply upload checks in your application: allowlisted extensions, content validation, size limits and controlled storage.
- Treat those checks as integration safeguards recommended by OWASP—not as independently verified Skavio implementation details. Neither a supplied Content-Type nor a file signature alone establishes that an upload is safe.
3. Preserve request identity while the job runs
Create a durable application record before submitting. Store the intended operation, source references, page plan and idempotency key. Keep the key stable when retrying the same logical request after a timeout; the documentation identifies it as the mechanism for retrying without starting another job. Do not change the inputs while presenting the request as an unchanged retry. The documented submission response includes the job state and exact credit quote. Record both, and use the quote for that specific job rather than importing rates from another processing product. A returned quote is not evidence of completion. The inspected contract does not establish a separate quote endpoint or a pre-execution approval stage; this guide does not quote numeric prices. Track the asynchronous job through GET /agent-tools/api/jobs/{idempotency_key}. Use bounded polling with delays rather than a tight loop. When available is true, retrieve the files listed in the response. Otherwise, report the returned state accurately and do not invent completion or assume the job is still running. An accepted request is not a deliverable.
4. Download the returned artifacts and check their bytes
The documented authenticated download route is GET /agent-tools/api/jobs/{idempotency_key}/results/{result_id}/download. Use the result identifiers returned by the service rather than guessing filenames, result counts or packaging. Keep downloads server-side so the company key is not exposed to recipients. The documentation specifies an X-Result-SHA256 response header. As an acceptance check, calculate SHA-256 over the downloaded bytes and compare it with that value. A missing or mismatched digest should hold the handoff for investigation. A match checks consistency with the supplied digest; it does not establish that the correct pages were selected. Retrieve results promptly. The documented result-retention period is seven days, so copy approved outputs into storage governed by your own access and retention policy rather than treating the job service as a permanent archive.
5. Approve the pages before releasing the PDF
Open the downloaded output and compare it with the page plan. For the fictional merge test, verify all five labels in the intended sequence. For a split, check the selected source pages and confirm that unrelated pages are absent. Only then mark the document ready for downstream use. Page manipulation can also have document-level consequences. QPDF’s documentation describes limitations involving bookmarks, forms and metadata during page selection. That supports inspecting these features where they matter; it does not establish that Skavio uses QPDF or behaves identically. Do not promise preservation of signatures, forms, bookmarks or metadata without verification. Keep a small audit record linking the source references, intended transformation, job identity, downloaded artifact and review outcome. The useful boundary is simple: technical completion makes a file available; document review makes it suitable for the next step.
- Check page count, sequence, duplicates and omissions.
- Inspect orientation and readability, including pages at document boundaries.
- Hold unexpected or incomplete output for review instead of silently forwarding it.