API documentation

Base URL https://reimply.com/v1. Requests and replies are JSON unless you send a multipart file or ask for raw bytes. The machine-readable spec is at /v1/openapi.json.

Authentication

Create keys in your account. A key is shown once, so store it in a secret manager. Send it as Authorization: Bearer rmk_... (or X-API-Key). You can name keys, see the usage of each and revoke them at any time.

Your first request

curl https://reimply.com/v1/convert \
  -H "Authorization: Bearer $REIMPLY_API_KEY" \
  -H "Accept: application/octet-stream" \
  -F "file=@file.png" \
  -F "to=jpg" \
  -F 'options={"quality":85}' \
  -o file.jpg

With Accept: application/octet-stream and a single result of 4 MB or less you get the file bytes back, with the job id in x-reimply-job and the conversions used in x-reimply-conversions. Authenticated replies also send Reimply-Quota-Limit, Reimply-Quota-Remaining and Reimply-Quota-Reset. Otherwise the reply is a job object:

{
  "object": "job",
  "id": "job_8sVJ0m1Yp2xq",
  "operation": "convert",
  "status": "succeeded",
  "mode": "sync",
  "processing_seconds": 0.42,
  "input_bytes": 1048576,
  "conversions": { "reserved": 1, "charged": 1 },
  "outputs": [
    { "index": 0, "name": "screenshot.jpg", "size": 182311, "content_type": "image/jpeg",
      "url": "https://reimply.com/v1/files/..." }
  ],
  "expires_at": "2026-11-19T15:04:05.000Z",
  "error": null
}

Sending files

Three ways, for any endpoint:

  • Multipart: a file field (or several files), with to, options (a JSON string), async and webhook_url as fields. Up to 4 MB in total.
  • A URL: {"input": "https://..."} or {"input": {"url": "https://...", "filename": "a.heic"}}. We download it (up to 5 redirects). Private and local addresses are refused.
  • A presigned upload for anything bigger: POST /v1/uploads, PUT the bytes, then pass {"upload_id": "upl_..."}. An upload can be used once and is deleted after 60 minutes.
# 1. Ask for an upload URL
curl https://reimply.com/v1/uploads \
  -H "Authorization: Bearer $REIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "talk.mov", "size": 52428800}'

# 2. PUT the bytes to the "url" from the reply, with its "headers"
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/quicktime" --data-binary @talk.mov

# 3. Start the job with the upload id and a webhook
curl https://reimply.com/v1/convert \
  -H "Authorization: Bearer $REIMPLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"upload_id": "upl_..."}, "to": "mp4", "webhook_url": "https://example.com/hooks/reimply"}'

Sync and async jobs

A job runs synchronously and returns its result when the input is known to be 4 MB or less. It runs in the background, answering 202 with a Location header, when you set "async": true, set a webhook_url, or send a presigned upload over 4 MB. Poll GET /v1/jobs/{id} or wait for the webhook. Status goes queued, running, then succeeded or failed. Results and inputs are deleted 60 minutes after the job; links in the job expire at expires_at.

Webhooks

Wenn ein Hintergrundauftrag endet, senden wir job.succeeded oder job.failed per POST an Ihre webhook_url, mit dem Auftragsobjekt in data. Eine 2xx-Antwort gilt als zugestellt; sonst wiederholen wir es bis zu 5 Mal: sofort, dann nach 10 Sekunden, 1 Minute, 5 Minuten und 30 Minuten. Jede Anfrage trägt reimply-event-id, reimply-event-type und reimply-signature. Prüfen Sie, dass der Zeitstempel aktuell ist, um Wiederholungen abzuwehren.

{ "id": "evt_...", "type": "job.succeeded", "created": 1763550000, "data": { "object": "job", "id": "job_...", ... } }
import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the exact request body as a string. header: the reimply-signature header.
export function verifyReimply(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(parts.v1 || '')
  return a.length === b.length && timingSafeEqual(a, b)
}

Send yourself a signed test event with POST /v1/webhooks/test {"url": "https://..."}.

Endpoints

POST/v1/convertConvert one file: {"input", "to", "options"}. Options: quality, dpi, height, crf, fps, audio_bitrate.
POST/v1/compressCompress an image, PDF, audio or video. options.target_size ("200kb", "1mb") hits an exact size for images and PDFs.
POST/v1/mergeMerge 2 to 20 PDFs (images are added as pages) in the order given.
POST/v1/splitSplit a PDF: {"options": {"mode": "each"}} or {"mode": "ranges", "ranges": "1-3,4-"}.
POST/v1/organizeReorder, remove and rotate pages: {"options": {"pages": [3,1,2], "rotate": {"1": 90}}}.
POST/v1/images-to-pdf1 to 20 images into one PDF. options.page_size: "a4" or "fit".
POST/v1/pdf-to-imagesRender pages as png, jpg or webp. options.format, options.dpi (36 to 300).
POST/v1/ocrText from an image or a scanned PDF (up to 30 pages). options.lang: eng, deu, fra, spa, ita, por, nld.
POST/v1/ingestDigital PDF, DOCX, CSV, TSV or JSON to Markdown, tables and chunks. Growth and Scale only. options.chunk_size (default 512).
POST/v1/optimizeShrink an image or PDF to options.max_bytes. Returns 422 target_unreachable and charges nothing if the cap cannot be reached.
POST/v1/uploadsGet a presigned PUT URL for files over 4 MB.
GET/v1/jobs/{id}Job status, conversions and signed output links.
GET/v1/jobsYour recent jobs.
GET/v1/jobs/{id}/outputs/{n}Redirects to output n.
GET/v1/accountPlan, conversion balances, usage and quota headers.
POST/v1/webhooks/testSend a signed test event to a URL.
GET/v1/conversionsEvery supported format pair. No key needed.
GET/v1/openapi.jsonThe OpenAPI 3.1 description. No key needed.

Ingest

POST /v1/ingest macht aus einem digitalen PDF, einem Word-Dokument (DOCX) oder einer CSV-, TSV- oder JSON-Datei Markdown, Tabellen als JSON (wenn sie erkennbar sind) und Abschnitte von etwa 512 Tokens (options.chunk_size, 64 bis 4096). Token-Angaben sind Näherungen (etwa 4 Zeichen pro Token). Bei PDFs gibt es Angaben je Seite. Dateien werden im Arbeitsspeicher verarbeitet und nicht auf die Festplatte geschrieben. Ingest führt kein OCR aus. Ein PDF ohne lesbaren Text, oder mit durchschnittlich unter etwa 20 Zeichen je Seite, ergibt 422 ocr_required_unsupported ohne Berechnung. Der Auftrag kostet 1 Konvertierung. Ingest ist in Growth (39 £) und Scale enthalten; Free und Starter erhalten 403 plan_upgrade_required mit einem Upgrade-Link.

Optimize

POST /v1/optimize verkleinert ein Bild oder PDF auf options.max_bytes (Bytes oder eine Angabe wie "100kb"). Bei Bildern kann options.format jpg, webp oder png sein. Liegt die Datei bereits unter der Grenze, wird sie unverändert zurückgegeben. Ist die Grenze nicht erreichbar, kommt 422 target_unreachable mit bytes_achieved und max_bytes, ohne Berechnung. Der Auftrag kostet 1 Konvertierung.

MCP server

Ein offizieller MCP-Server ist als npm-Paket @reimply/mcp-server verfügbar. Hinterlegen Sie REIMPLY_API_KEY für Claude Desktop, Cursor oder Windsurf. Der Server kann konvertieren, optimieren, ingestieren, Konvertierungen listen und den Kontostand lesen und akzeptiert lokale Dateipfade. Die Einrichtung steht in der README des Pakets.

Konvertierungen

1 Datei = 1 Konvertierung. Video- und Audio-Aufträge zählen als 3. Dateigröße und Verarbeitungszeit zählen nicht extra. Konvertierungen werden beim Start reserviert und bei einem Fehler vollständig erstattet. Siehe Preise. GET /v1/account zeigt Ihr Guthaben. Jede authentifizierte /v1-Antwort enthält Reimply-Quota-Limit (monatliches Kontingent), Reimply-Quota-Remaining (verbleibende Konvertierungen in diesem Zeitraum) und Reimply-Quota-Reset (Unix-Zeit des nächsten monatlichen Resets). See Preise.

Limits and rate limits

  • Uploads up to 1 GB. Processing limits: images 100 MB, PDFs 250 MB, documents and data 25 MB, audio 500 MB, video 500 MB and 10 minutes. Larger files are refused with file_too_large bevor Konvertierungen verbraucht werden.
  • Synchronous requests and inline results: up to 4 MB.
  • A job can run for about 4 minutes; longer jobs fail and are not charged.
  • Ingest and optimize run in memory and are not written to disk during processing.
  • Requests a minute per key: Free 30, Starter 120, Growth 300, Scale 600. Every reply has x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; a 429 has retry-after.
  • Background jobs at once: Free 1, Starter 3, Growth 10, Scale 25.

Idempotency

Send Idempotency-Key: any-unique-string on POST requests to retry safely. For 24 hours the same key with the same request returns the first reply (with idempotent-replayed: true) instead of running and charging again. The same key with a different request gets 422 idempotency_key_reused.

Errors

Errors are JSON: {"error": {"code": "insufficient_credits", "message": "...", "status": 402}}.

CodeStatusMeaning
invalid_request400The body or an option is missing or wrong. The message says which.
unauthorized401No API key was sent.
invalid_api_key401The key is unknown or revoked.
insufficient_credits402Not enough conversions for this job. Upgrade your plan.
forbidden403The key cannot access this resource.
plan_upgrade_required403This endpoint needs a higher plan. The message includes an upgrade link.
not_found404Unknown endpoint, job or file.
upload_not_found404Unknown, expired or already used upload_id.
idempotency_in_progress409A request with this Idempotency-Key is still running.
file_too_large413Over your plan cap, or over the processing limit for this file type.
unsupported_file_type415This endpoint does not take that kind of file.
file_mismatch415The file contents do not match its extension.
unsupported_conversion422That format pair is not available. See /v1/conversions.
conversion_failed422The file could not be processed (damaged, encrypted or empty). No conversions are charged.
ocr_required_unsupported422The PDF looks scanned or image-only. Ingest does not run OCR in this version, and nothing is charged.
target_unreachable422The byte cap could not be reached. The error includes bytes_achieved and max_bytes, and nothing is charged.
source_blocked422The source URL points to a private or local address.
source_fetch_failed422The source URL could not be downloaded.
idempotency_key_reused422The Idempotency-Key was used with a different request.
rate_limited429Too many requests a minute for this key. Wait for Retry-After seconds.
concurrency_limit429Too many background jobs running at once for your plan.
internal_error500Something went wrong on our side. Retrying is safe with an Idempotency-Key.
storage_unavailable503File storage is temporarily unavailable.
billing_unavailable503Purchasing is temporarily unavailable.