Developer guide

One workflow for every file tool.

Store sources, submit typed operations, and retrieve generated Files with lineage. The same model serves PDF workflows, Office conversions, spreadsheets, and photos.

Check your account setup API reference

What this guide covers

The file, the job, and the handoff.

Dislify keeps the developer model intentionally small: store a File, run an operation, retrieve generated Files, then poll or continue from an event.

Files

Durable sources + outputs

Jobs

Typed async operations

Events

Signed completion hooks

Saved multi-operation workflows

extract_text creates a durable UTF-8 TXT File from PDF/JPG/PNG. Existing meaningful PDF text is reused; other pages use local English OCR. The operation is terminal in workflows. Output is bounded to 2 MiB, with LF/no BOM and form-feed page separators. Download generated Files to read text; Jobs and signed events contain metadata only.

Compose up to five compatible steps such as Office to PDF then compression. POST /api/v1/workflows creates a definition; POST /api/v1/workflows/:id/runs accepts owned File IDs and an Idempotency-Key, returning a workflowRunId immediately. Poll /api/v1/workflow-runs/:id for steps and final outputs.

SDK 0.9.0 is prepared and unpublished: workflows.create, run, wait, retry and downloadZip. Each step uses the normal plan/storage/API quota. Runs keep immutable snapshots; retries accept the failed attempt ID and preserve successful previous steps. Signed job events include workflow correlation. No branching, scheduled invocations or arbitrary HTTP steps.

File-processing quickstart

One lifecycle for every tool.

Store a source File, submit an operation, then poll or continue from a signed webhook. Developer API access requires Unlimited.

Manage API keys REST reference

Authenticate

Use one server-side API key.

Store a File

Upload once and keep the File ID.

Process + retrieve

Run a typed job, then fetch generated Files.

SDK example

Upload → process → download → inspect lineage.

Server-side

file-processing.ts

View on npm

// Repository SDK 0.5.0; npm publication is a separate release step.
// npm install @dislify/sdk (use 0.5.0 once it is published)
import { readFile, writeFile } from "node:fs/promises"
import { DislifyClient } from "@dislify/sdk"

const client = new DislifyClient({ apiKey: process.env.DISLIFY_API_KEY! })

const source = await client.files.upload(
  new Blob([await readFile("proposal.docx")]),
  {
    fileName: "proposal.docx",
    contentType:
      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  }
)

const submitted = await client.files.convert(source.id, { format: "pdf" })
const result = await client.processing.wait(submitted.id)

for (const output of result.generatedFiles) {
  const bytes = await client.files.download(output.id)
  await writeFile(output.name, Buffer.from(await bytes.arrayBuffer()))
}

const history = await client.files.get(result.generatedFiles[0].id)
console.log(history.parents.map((file) => file.id))

Running this from the CLI? Use node --env-file=.env app.mjs, or load dotenv/config.

For upload limits, use client.processing.compressPdf(fileId, { targetSizeBytes: 2 * 1024 ** 2, idempotencyKey: "pdf-limit-1" }) or compressImage for JPG/PNG. Choose a target or preset; unreachable targets fail without output.

Office batches return independent child job IDs. Split PDF and PDF-to-images can return multiple generated Files. Sources remain unchanged and retention follows the account plan or connected bucket.

Authenticate

POST /api/v1/developers/token with your API key, then keep the returned Bearer token server-side.

Create a source File

Prepare a signed upload with POST /api/v1/uploads, upload the bytes, then finalize it with POST /api/v1/files.

Submit an operation

Send owned File IDs to POST /api/v1/processing/jobs with one supported operation. The response includes job IDs and an optional batch ID.

Read the result

Poll GET /api/v1/processing/jobs/:id or receive a signed job event. Generated Files are durable outputs with source lineage.

Download safely

Read File metadata with GET /api/v1/files/:id, then request a short-lived download URL from the File download endpoint.

Processing operations

Browser tools, REST jobs, and SDK helpers share the same operation model.

23 operations

Watermark image

watermark_image

One still JPG / PNG / WebP → One same-format image with a text overlay

Options

text: 1–120 printable ASCII characters; fontSize: 8–512 source pixels (32); margin: 0–1024 (16); opacity: 0.05–1 (0.5); color: #RRGGBB (#000000); nine positions (bottom_right)

Independent batch/retry/ZIP; same-format workflow step. 50 MiB source/output plus plan limits; 8192px side; 20M pixels; bundled Bitstream Vera; no private metadata copied; original unchanged.

SDK

client.processing.watermarkImage(id, { text: "DRAFT" })

/watermark-image

Crop / rotate image

crop_rotate_image

One still JPG / PNG → One same-format cropped/rotated File

Options

rotation: 0 | 90 | 180 | 270 clockwise; optional x, y, width, height integer pixels after orientation normalization and rotation; omit all crop fields for full image

Independent batch/retry/ZIP; workflow. Same pixel rectangle per image; out-of-bounds items fail individually. 50 MiB source/output plus plan limits; 8192px side; 20M pixels; no private metadata copied; JPG re-encoded at quality 95.

SDK

client.processing.cropRotateImage(id, { rotation: 90 })

/crop-rotate-image

Remove PDF metadata

remove_pdf_metadata

One verified static unsigned PDF per item; comments/layers/external content excluded → One newly written PDF without supported document metadata

Options

No options. Info, reachable Metadata/XMP, editing history, thumbnails and source IDs removed; original revisions discarded.

Independent batch/retry/ZIP; single-input PDF workflow step. 2,000 pages; existing plan/250 MiB bounds; visible text, image/font assets and retained functional content are not anonymized; source unchanged.

SDK

client.processing.removePdfMetadata(id, { idempotencyKey: "pdf-metadata-1" })

/remove-pdf-metadata

Add page numbers

add_pdf_page_numbers

One verified static, unsigned PDF per item → One new vector-preserving numbered PDF

Options

format: number | page_number | number_of_total | page_number_of_total; six top/bottom positions; startNumber (1–999999); pages (empty = all); fontSize (8–24pt); #RRGGBB color; opacity (0.3–1); margin (12–72pt)

Independent batch/retry/ZIP; single-input PDF workflow step. Number selected physical pages consecutively; N is the final assigned number.. Embedded Bitstream Vera; 2,000 pages; existing plan/250 MiB bounds; signed/forms/active PDFs rejected; overlays existing numbers.

SDK

client.processing.addPdfPageNumbers(id, { format: "number", position: "bottom_center", startNumber: 1, pages: [], fontSize: 12, color: "#294B3D", opacity: 1, margin: 24 })

/add-pdf-page-numbers

Watermark PDF

watermark_pdf

One verified static, unsigned PDF per item → One new vector-preserving PDF with a text overlay

Options

mode: text, text, fontSize (8–96pt), opacity (0.05–0.6), rotation (-180–180), #RRGGBB color, position, pages (empty = all)

Independent batch/retry/ZIP; single-input PDF workflow step. Printable ASCII / embedded Bitstream Vera; 120 characters; 2,000 pages; existing plan/250 MiB bounds; signed/forms/active PDFs rejected; logo input deferred.

SDK

client.processing.watermarkPdf(id, { mode: "text", text: "DRAFT", fontSize: 36, opacity: 0.2, rotation: 45, color: "#294B3D", position: "center", pages: [] })

/watermark-pdf

Remove background

remove_background

Still JPG / PNG / WebP; up to 12 million pixels and existing plan limits → Transparent-capable RGBA PNG at oriented source dimensions

Options

No options

Independent jobs, retry and ZIP; workflows. Local CPU inference; 50 MiB maximum source/output, 8192px per side, 12 million pixels; plan limits apply.

SDK

client.processing.removeBackground(id, { idempotencyKey: 'remove-bg-v1' })

/remove-background

Remove image metadata

strip_image_metadata

One still JPG / PNG / WebP → One sanitized File in the same format

Options

No options; orientation normalized; metadata removed

Independent jobs, retry and ZIP; workflows. 50 MiB source/output and plan cap; 20M pixels; 8192 px side; image queue.

SDK

client.processing.stripImageMetadata(id)

/strip-image-metadata

Convert image

convert_image

One still JPG / PNG / WebP → One JPG / PNG / WebP File in the selected different format

Options

format: jpg | png | webp; same-format conversion rejected

Independent jobs, retry and ZIP; workflows. 50 MiB source/output and plan cap; 20M pixels; 8192 px side; image queue.

SDK

client.processing.convertImage(id, { format: "webp" })

/convert-image

Resize image

resize_image

One still JPG / PNG → One same-format resized File

Options

width and/or height: 1–8192 whole pixels; OR percent: 1–400 integer; aspect-preserving fit; half-pixels round up

Independent jobs, batch retry and ZIP; workflows. 50 MiB source/output + plan cap; 20M pixels; 8192 side; no-op is an error; image queue.

SDK

client.processing.resizeImage(id, { width: 1200 })

/resize-image

Extract text

extract_text

Static PDF / JPG / PNG scan → One UTF-8 TXT File per source

Options

language: eng; existing PDF text first, local OCR fallback; LF and form-feed page boundaries

Independent jobs for ordered sources; shared batch/retry/ZIP; terminal workflow step. 20 MiB source; 2 MiB TXT; Free/Pro/Unlimited 3/10/20 PDF pages, 3/30/60 batch pages; OCR queue.

SDK

client.processing.extractText(id, { language: "eng" })

/extract-text

OCR searchable PDF

ocr_pdf

Scanned or hybrid static PDF → One searchable PDF per source

Options

language: eng (English); already-searchable pages retained

Independent jobs for ordered sources; shared batch/retry/ZIP. 20 MiB source; Free/Pro/Unlimited 3/10/20 pages per source, 3/30/60 batch pages; 300 DPI; isolated OCR queue.

SDK

client.processing.ocrPdf(id, { language: "eng" })

/ocr-pdf

Image to searchable PDF

image_to_searchable_pdf

JPG / PNG still scan → One searchable PDF per source

Options

language: eng (English); EXIF orientation normalized

Independent jobs for ordered sources; shared batch/retry/ZIP. 20 MiB source; 16M pixels and 6,000 px side; Free/Pro/Unlimited 1/10/20 sources; isolated OCR queue.

SDK

client.processing.imageToSearchablePdf(id, { language: "eng" })

/ocr-pdf

Office to PDF

office_to_pdf

DOCX / XLSX / PPTX → PDF per source

Options

No options

Independent jobs for ordered sources. 50 MiB per source; plan batch cap; 250 MiB combined.

SDK

client.files.convert(ids, { format: "pdf" })

/word-to-pdf /excel-to-pdf /powerpoint-to-pdf

Images to PDF

images_to_pdf

JPG / PNG → One PDF

Options

No options; source order is page order

Ordered sources → one job. 20M pixels per image; 40M total; Free one image, Pro 25, Unlimited 100.

SDK

client.files.convert(ids, { format: "pdf", operation: "images_to_pdf" })

/jpg-to-pdf

Merge PDF

merge_pdf

Two or more PDFs → One PDF

Options

No options; preserve input order

Ordered sources → one job. Free 2, Pro 25, Unlimited 100 inputs; 2,000 pages; 250 MiB combined.

SDK

client.processing.mergePdf(ids)

/merge-pdf

Split / extract PDF

split_pdf

One PDF → One or more PDFs

Options

mode: extract + pages: "1,3,5-8"; ranges + ranges: ["1-3","4-6"]; every_page

One job → multiple Files. 2,000 source pages; Free/Pro/Unlimited 10/50/100 outputs.

SDK

client.processing.splitPdf(id, { mode: "extract", pages: "1,3-5" })

/split-pdf

Organize PDF

organize_pdf

One PDF → One PDF

Options

pages: [{ page: 4, rotation: 90 }, { page: 1, rotation: 0 }]; one-based source pages; rotation 0/90/180/270

Ordered page plan → one File. 1–2,000 unique source pages; omitted pages removed.

SDK

client.processing.organizePdf(id, { pages })

/organize-pdf

PDF to JPG / PNG

pdf_to_images

One PDF → JPG / PNG per page

Options

format: jpg | png; pages: [1,3]; server sorts into source order

One job → multiple Files. 144 DPI; 4,096 px side; 12M pixels per page; 10/50/100 outputs; aggregate output cap.

SDK

client.processing.pdfToImages(id, { format: "png", pages: [1,3] })

/pdf-to-jpg /pdf-to-png

Compress PDF

compress_pdf

One PDF → One smaller PDF

Options

preset: best_quality | balanced | smaller_file OR targetSizeBytes: integer maximum output bytes; mutually exclusive

Independent jobs for ordered sources; one File per source. Static PDF; 2,000 pages; target 16 KiB minimum and 5–95% of source; plan byte caps; strict target or safe error.

SDK

client.processing.compressPdf(id, { targetSizeBytes: 5 * 1024 * 1024 })

/compress-pdf

Compress image

compress_image

One JPG / PNG still → One smaller JPG, or PNG preserving transparency

Options

preset: best_quality | balanced | smaller_file OR targetSizeBytes: integer maximum; mutually exclusive

Independent jobs for ordered sources; one File per source. 50 MiB + plan cap; 20M pixels; 8,192 px side; target 16 KiB minimum and 5–95% of source; image queue.

SDK

client.processing.compressImage(id, { targetSizeBytes: 2 * 1024 * 1024 })

/compress-image

CSV to Excel

csv_to_xlsx

UTF-8 CSV → One XLSX

Options

delimiter: auto (default) | comma | semicolon | tab | pipe

Independent jobs for ordered sources; one File per source. 50 MiB and plan cap; values stored as literal text.

SDK

client.processing.csvToXlsx(id, { delimiter: "auto", idempotencyKey: "export-1" })

/csv-to-excel

Excel to CSV

xlsx_to_csv

One XLSX worksheet → UTF-8 BOM / CRLF CSV

Options

sheet: exact worksheet name; delimiter: comma (default) | semicolon | tab | pipe; omit sheet only for one visible worksheet

Independent jobs for ordered sources; one File per source. 50 MiB and plan cap; cached formula values only; inspect files.worksheets(id).

SDK

client.processing.xlsxToCsv(id, { sheet: "Sales", delimiter: "comma" })

/excel-to-csv

HEIC to JPG / PNG

heic_to_image

HEIC / HEIF primary still → One JPG / PNG

Options

format: jpg | png

Independent jobs for ordered sources; one File per source. 50 MiB source + plan cap; 20M pixels; 8,192 px side; SDR only; native image consumer required.

SDK

client.processing.heicToImage(id, { format: "jpg", idempotencyKey: "photo-1" })

/heic-to-jpg

Maximum-size compression

Submit {"fileIds":["source-id"],"operations":[{"type":"compress_pdf","targetSizeBytes":2097152}]}, or use compress_image for JPG/PNG. Choose exactly one of integer targetSizeBytes or preset (best_quality, balanced, smaller_file). Targets are at least 16 KB, 5–95% of the source and within plan/output limits. 1 MB = 1,048,576 bytes. Completion means independently verified stored bytes are at or below the target. An unreachable target or no-savings error creates no output File or output storage charge; try a larger target or preset.

Generic signed events include sanitized target/preset options, source IDs and actual generated File sizes. Failed targets have no successful output. Guests have no account webhook endpoints. SDK 0.5.0 is prepared in the repository; npm publication is a separate release step.

Limits + errors

Developer tokens require Unlimited and the correct scopes. Expect standard 4xx responses for invalid options, ownership, limits, quota, and unsupported formats. Native dispatch failures may transition an accepted job to error.

Idempotency

CSV→XLSX, XLSX→CSV, HEIC→image, Compress PDF and Compress image support Idempotency-Key. Reuse a key only for the same owner, source, and options. Other processing submissions are not retried automatically.

Signed events

Subscribe to job.queued, job.completed, and job.failed. Verify HMAC-SHA256 against the exact raw body and deduplicate by event ID. Delivery is currently best effort without automatic replay.

Current API quotas are 60 job submissions per hour and 10,000 per month for eligible accounts; operation-specific caps and normal storage retention still apply.