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

Quand une tâche en arrière-plan se termine, nous envoyons job.succeeded ou job.failed en POST vers votre webhook_url, avec l’objet tâche dans data. Une réponse 2xx compte comme reçue ; sinon nous réessayons jusqu’à 5 fois : tout de suite, puis après 10 secondes, 1 minute, 5 minutes et 30 minutes. Chaque requête porte reimply-event-id, reimply-event-type et reimply-signature. Vérifiez que l’horodatage est récent pour bloquer les rejeux.

{ "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 transforme un PDF numérique, un document Word (DOCX) ou un fichier CSV, TSV ou JSON en Markdown, en tableaux JSON lorsqu’ils peuvent être trouvés, et en morceaux d’environ 512 jetons (options.chunk_size, de 64 à 4096). Les comptes de jetons sont approximatifs (environ 4 caractères par jeton). Les réponses PDF incluent des métadonnées par page. Les fichiers sont traités en mémoire, pas écrits sur le disque. Ingest n’exécute pas d’OCR. Un PDF sans texte extractible, ou avec moins d’environ 20 caractères par page en moyenne, renvoie 422 ocr_required_unsupported et n’est pas facturé. Le travail coûte 1 conversion. Ingest est disponible sur Growth (39 £) et Scale ; les comptes Free et Starter reçoivent 403 plan_upgrade_required avec un lien de mise à niveau.

Optimize

POST /v1/optimize réduit une image ou un PDF à options.max_bytes (un nombre d’octets, ou une taille comme "100kb"). Pour les images, options.format peut être jpg, webp ou png. Si le fichier tient déjà sous la limite, il est renvoyé tel quel. Si la limite est inatteignable, vous recevez 422 target_unreachable avec bytes_achieved et max_bytes, sans facturation. Le travail coûte 1 conversion.

MCP server

Un serveur MCP officiel est disponible en paquet npm @reimply/mcp-server. Configurez Claude Desktop, Cursor ou Windsurf avec REIMPLY_API_KEY. Il peut convertir, optimiser, ingérer, lister les conversions et lire l’usage du compte, et il accepte des chemins de fichiers locaux. Voir le README du paquet pour la configuration.

Conversions

1 fichier = 1 conversion. Les tâches vidéo et audio comptent pour 3. La taille et le temps de traitement n’ajoutent pas de conversions. Les conversions sont réservées au démarrage et remboursées en entier en cas d’échec. Voir les tarifs. GET /v1/account renvoie vos soldes. Chaque réponse /v1 authentifiée inclut Reimply-Quota-Limit (quota mensuel), Reimply-Quota-Remaining (conversions restantes sur la période) et Reimply-Quota-Reset (heure Unix de la prochaine réinitialisation mensuelle). See Tarifs.

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 avant toute consommation de conversions.
  • 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.