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.jpgimport { readFile, writeFile } from 'node:fs/promises'
const form = new FormData()
form.append('file', new Blob([await readFile('file.png')]), 'file.png')
form.append('to', 'jpg')
form.append('options', JSON.stringify({"quality":85}))
const res = await fetch('https://reimply.com/v1/convert', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.REIMPLY_API_KEY}` },
body: form,
})
const job = await res.json()
if (!res.ok) throw new Error(job.error.message)
for (const o of job.outputs) {
const file = await fetch(o.url)
await writeFile(o.name, Buffer.from(await file.arrayBuffer()))
}
console.log(job.id, 'used', job.credits.charged, 'credit(s)')import os, requests
with open("file.png", "rb") as f:
res = requests.post(
"https://reimply.com/v1/convert",
headers={"Authorization": f"Bearer {os.environ['REIMPLY_API_KEY']}"},
files={"file": f},
data={"to": "jpg", "options": '{"quality":85}'},
)
job = res.json()
res.raise_for_status()
for o in job["outputs"]:
with open(o["name"], "wb") as out:
out.write(requests.get(o["url"]).content)
print(job["id"], "used", job["credits"]["charged"], "credit(s)")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
filefield (or severalfiles), withto,options(a JSON string),asyncandwebhook_urlas 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"}'import { readFile, stat } from 'node:fs/promises'
const auth = { Authorization: `Bearer ${process.env.REIMPLY_API_KEY}` }
const { size } = await stat('talk.mov')
const up = await (await fetch('https://reimply.com/v1/uploads', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json' },
body: JSON.stringify({ filename: 'talk.mov', size }),
})).json()
await fetch(up.url, { method: 'PUT', headers: up.headers, body: await readFile('talk.mov') })
const res = await fetch('https://reimply.com/v1/convert', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json' },
body: JSON.stringify({ input: { upload_id: up.id }, to: 'mp4', async: true }),
})
let job = await res.json() // 202, status "queued"
while (job.status === 'queued' || job.status === 'running') {
await new Promise((r) => setTimeout(r, 3000))
job = await (await fetch(`https://reimply.com/v1/jobs/${job.id}`, { headers: auth })).json()
}
console.log(job.status, job.outputs)import os, time, requests
auth = {"Authorization": f"Bearer {os.environ['REIMPLY_API_KEY']}"}
size = os.path.getsize("talk.mov")
up = requests.post("https://reimply.com/v1/uploads", headers=auth, json={"filename": "talk.mov", "size": size}).json()
with open("talk.mov", "rb") as f:
requests.put(up["url"], headers=up["headers"], data=f)
job = requests.post("https://reimply.com/v1/convert", headers=auth,
json={"input": {"upload_id": up["id"]}, "to": "mp4", "async": True}).json()
while job["status"] in ("queued", "running"):
time.sleep(3)
job = requests.get(f"https://reimply.com/v1/jobs/{job['id']}", headers=auth).json()
print(job["status"], job["outputs"])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)
}import hmac, hashlib, time
def verify_reimply(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", "0"))
if not t or abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Send yourself a signed test event with POST /v1/webhooks/test {"url": "https://..."}.
Endpoints
| POST | /v1/convert | Convert one file: {"input", "to", "options"}. Options: quality, dpi, height, crf, fps, audio_bitrate. |
| POST | /v1/compress | Compress an image, PDF, audio or video. options.target_size ("200kb", "1mb") hits an exact size for images and PDFs. |
| POST | /v1/merge | Merge 2 to 20 PDFs (images are added as pages) in the order given. |
| POST | /v1/split | Split a PDF: {"options": {"mode": "each"}} or {"mode": "ranges", "ranges": "1-3,4-"}. |
| POST | /v1/organize | Reorder, remove and rotate pages: {"options": {"pages": [3,1,2], "rotate": {"1": 90}}}. |
| POST | /v1/images-to-pdf | 1 to 20 images into one PDF. options.page_size: "a4" or "fit". |
| POST | /v1/pdf-to-images | Render pages as png, jpg or webp. options.format, options.dpi (36 to 300). |
| POST | /v1/ocr | Text from an image or a scanned PDF (up to 30 pages). options.lang: eng, deu, fra, spa, ita, por, nld. |
| POST | /v1/ingest | Digital PDF, DOCX, CSV, TSV or JSON to Markdown, tables and chunks. Growth and Scale only. options.chunk_size (default 512). |
| POST | /v1/optimize | Shrink an image or PDF to options.max_bytes. Returns 422 target_unreachable and charges nothing if the cap cannot be reached. |
| POST | /v1/uploads | Get a presigned PUT URL for files over 4 MB. |
| GET | /v1/jobs/{id} | Job status, conversions and signed output links. |
| GET | /v1/jobs | Your recent jobs. |
| GET | /v1/jobs/{id}/outputs/{n} | Redirects to output n. |
| GET | /v1/account | Plan, conversion balances, usage and quota headers. |
| POST | /v1/webhooks/test | Send a signed test event to a URL. |
| GET | /v1/conversions | Every supported format pair. No key needed. |
| GET | /v1/openapi.json | The 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_largebefore 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-remainingandx-ratelimit-reset; a 429 hasretry-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}}.
| Code | Status | Meaning |
|---|---|---|
| invalid_request | 400 | The body or an option is missing or wrong. The message says which. |
| unauthorized | 401 | No API key was sent. |
| invalid_api_key | 401 | The key is unknown or revoked. |
| insufficient_credits | 402 | Not enough conversions for this job. Upgrade your plan. |
| forbidden | 403 | The key cannot access this resource. |
| plan_upgrade_required | 403 | This endpoint needs a higher plan. The message includes an upgrade link. |
| not_found | 404 | Unknown endpoint, job or file. |
| upload_not_found | 404 | Unknown, expired or already used upload_id. |
| idempotency_in_progress | 409 | A request with this Idempotency-Key is still running. |
| file_too_large | 413 | Over your plan cap, or over the processing limit for this file type. |
| unsupported_file_type | 415 | This endpoint does not take that kind of file. |
| file_mismatch | 415 | The file contents do not match its extension. |
| unsupported_conversion | 422 | That format pair is not available. See /v1/conversions. |
| conversion_failed | 422 | The file could not be processed (damaged, encrypted or empty). No conversions are charged. |
| ocr_required_unsupported | 422 | The PDF looks scanned or image-only. Ingest does not run OCR in this version, and nothing is charged. |
| target_unreachable | 422 | The byte cap could not be reached. The error includes bytes_achieved and max_bytes, and nothing is charged. |
| source_blocked | 422 | The source URL points to a private or local address. |
| source_fetch_failed | 422 | The source URL could not be downloaded. |
| idempotency_key_reused | 422 | The Idempotency-Key was used with a different request. |
| rate_limited | 429 | Too many requests a minute for this key. Wait for Retry-After seconds. |
| concurrency_limit | 429 | Too many background jobs running at once for your plan. |
| internal_error | 500 | Something went wrong on our side. Retrying is safe with an Idempotency-Key. |
| storage_unavailable | 503 | File storage is temporarily unavailable. |
| billing_unavailable | 503 | Purchasing is temporarily unavailable. |