FlowynBETA
LoginSign up

Intelligent PDF Splitter

Scans a mixed PDF for document boundaries and splits it into child PDFs, each with its page range and a confidence score. Low-confidence groups are marked for review. Use `POST /v1/pdf/split` instead when you already know the page ranges.

What intelligent pdf splitter does

Scans a mixed PDF for document boundaries and splits it into child PDFs, each with its page range and a confidence score. Low-confidence groups are marked for review. Use POST /v1/pdf/split instead when you already know the page ranges.

When to use intelligent pdf splitter

  • Scanned intake batches
  • Mailroom digitisation
  • Archive cleanup

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/split-pdf

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/split-pdf \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: split-batch-16" \
  -d '{
    "file_id": "9c1e5b7a-2d4f-4a6b-8e3c-1f0a7d2b5c64"
  }'

Response

Flowyn returns HTTP 202. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "2b7d9e1f-4a6c-4b8d-9f2e-7c1a3e5d8b90",
  "object": "job",
  "operation": "split_pdf",
  "status": "queued",
  "file_id": "9c1e5b7a-2d4f-4a6b-8e3c-1f0a7d2b5c64",
  "request_id": "req_5f2a9c1e7b3d4a6f8e0c2b1d"
}

Lifecycle

  1. Upload the file with POST /v1/files (tus resumable upload). The response is the file with its id.
  2. Call POST /v1/split-pdf with the file_id. Flowyn stores the operation and returns HTTP 202 with a job id before any work starts.
  3. A managed worker claims the job, runs the operation, and records an attempt.
  4. Read GET /v1/file-jobs/{id}. When status is complete, outputs lists the produced files; download one with GET /v1/files/{id}/download.

Status values

StatusMeaning
queuedAccepted, waiting for a worker.
delayedWaiting before a scheduled retry.
processingA worker is running the operation.
retryingThe last attempt failed and another is scheduled.
completeOutputs are stored and listed in outputs.
failedThe operation could not complete; error explains why.
cancelledCancelled before it completed.

Retries

A file operation gets up to 3 attempts. Worker failures and timeouts are retried; an unreadable or unsupported file fails without a retry.

Idempotency

Send Idempotency-Key.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • Files up to 50 MB and 200 pages
  • Confidence is always reported; low-confidence boundaries are still returned and marked

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/file-jobs/2b7d9e1f-4a6c-4b8d-9f2e-7c1a3e5d8b90 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

Combine with Events to notify another system when a split completes.