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

When a background job finishes we POST job.succeeded or job.failed to your webhook_url, with the job object in data. A 2xx answer counts as delivered; otherwise we retry up to 5 times: immediately, then after 10 seconds, 1 minute, 5 minutes and 30 minutes. Each request carries reimply-event-id, reimply-event-type and reimply-signature: t=1763550000,v1=hex, where v1 is HMAC-SHA256 of "{t}.{raw body}" with your webhook secret (shown in your account, and rotatable). Check the timestamp is recent to stop replays.

{ "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 turns a digital PDF, Word document (DOCX), CSV, TSV or JSON file into Markdown, tables as JSON where they can be found, and chunks of about 512 tokens (set options.chunk_size from 64 to 4096). Token counts are approximate (about 4 characters per token); we do not ship a tokenizer. PDF replies include per-page character and token counts. Files are processed in memory, not written to disk. Ingest does not run OCR. If a PDF has no extractable text, or under about 20 characters per page on average, you get 422 ocr_required_unsupported and are not charged. The job costs 1 conversion. Ingest is available on Growth (£39) and Scale; Free and Starter accounts get 403 plan_upgrade_required with an upgrade link.

Optimize

POST /v1/optimize shrinks an image or PDF to options.max_bytes (a number of bytes, or a size like "100kb"). For images you can set options.format to jpg, webp or png. If the file is already at or under the cap, it is returned as is. If the cap cannot be reached, you get 422 target_unreachable with bytes_achieved and max_bytes, and nothing is charged. The job costs 1 conversion.

MCP server

An official MCP server is available as the npm package @reimply/mcp-server. Point Claude Desktop, Cursor or Windsurf at it with REIMPLY_API_KEY in the environment. It can convert, optimize, ingest, list conversions and read account usage, and it accepts local file paths. See the package README for setup.

Conversions

1 file = 1 conversion. Video and audio jobs count as 3. File size and processing time do not add conversions. Conversions are reserved when a job starts and refunded in full if it fails. See pricing. GET /v1/account returns your balances. Every authenticated /v1 response includes Reimply-Quota-Limit (your monthly allowance), Reimply-Quota-Remaining (conversions left in this period) and Reimply-Quota-Reset (Unix time of the next monthly reset). See Pricing.

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 before any conversions are used.
  • 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.