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

Cuando termina un trabajo en segundo plano, enviamos job.succeeded o job.failed por POST a tu webhook_url, con el objeto del trabajo en data. Una respuesta 2xx cuenta como entregada; si no, reintentamos hasta 5 veces: al momento, luego a los 10 segundos, 1 minuto, 5 minutos y 30 minutos. Cada petición lleva reimply-event-id, reimply-event-type y reimply-signature. Comprueba que la marca de tiempo sea reciente para evitar repeticiones.

{ "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 convierte un PDF digital, un documento Word (DOCX) o un archivo CSV, TSV o JSON en Markdown, tablas en JSON cuando se pueden encontrar, y fragmentos de unos 512 tokens (options.chunk_size, de 64 a 4096). El recuento de tokens es aproximado (unos 4 caracteres por token). Las respuestas PDF incluyen metadatos por página. Los archivos se procesan en memoria, no se escriben en disco. Ingest no ejecuta OCR. Un PDF sin texto extraíble, o con menos de unos 20 caracteres por página de media, devuelve 422 ocr_required_unsupported y no se cobra. El trabajo cuesta 1 conversión. Ingest está en Growth (39 £) y Scale; las cuentas Free y Starter reciben 403 plan_upgrade_required con un enlace de mejora.

Optimize

POST /v1/optimize reduce una imagen o un PDF a options.max_bytes (bytes, o un tamaño como "100kb"). En imágenes, options.format puede ser jpg, webp o png. Si el archivo ya cabe, se devuelve tal cual. Si no se alcanza el límite, recibes 422 target_unreachable con bytes_achieved y max_bytes, sin cargo. El trabajo cuesta 1 conversión.

MCP server

Hay un servidor MCP oficial en el paquete npm @reimply/mcp-server. Configura Claude Desktop, Cursor o Windsurf con REIMPLY_API_KEY. Puede convertir, optimizar, ingerir, listar conversiones y leer el uso de la cuenta, y acepta rutas de archivos locales. La configuración está en el README del paquete.

Conversiones

1 archivo = 1 conversión. Los trabajos de vídeo y audio cuentan como 3. El tamaño y el tiempo de proceso no suman conversiones. Las conversiones se reservan al empezar y se devuelven por completo si falla. Consulta los precios. GET /v1/account devuelve tus saldos. Cada respuesta /v1 autenticada incluye Reimply-Quota-Limit (cupo mensual), Reimply-Quota-Remaining (conversiones que quedan en este periodo) y Reimply-Quota-Reset (hora Unix del próximo reinicio mensual). See Precios.

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 antes de usar conversiones.
  • 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.