CDR API Documentation

Getting started

The Red Eagle Tech Content Disarm and Reconstruction (CDR) API sanitises documents to remove potential security threats while preserving document usability. Most integrations are live within the hour.

The 60-second integration

1. Get credentials - sign up at account.redeagle.tech, buy pay-as-you-go credit or a plan, and your API client id and secret are issued on the spot (the secret is shown once - store it in your secret manager).
2. Get a token - OAuth2 client credentials, scope cdr.api. Tokens last an hour; cache and reuse them.
3. Sanitise - one call with ?wait=true returns the cleaned file link for most documents in seconds; larger files transition gracefully to a short poll.

Authentication

The CDR API uses OAuth2 client credentials: exchange your client id and secret for a short-lived bearer token, then send it on every request. There is nothing to sign - and if your integration runs on a workflow platform that cannot perform a token exchange, API keys are available as an alternative credential.

TOKEN=$(curl -s https://identity.redeagle.tech/connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CDR_CLIENT_ID" \
  -d client_secret="$CDR_CLIENT_SECRET" \
  -d scope=cdr.api | jq -r .access_token)

API keys - for integration platforms

Some places an integration runs cannot perform an OAuth token exchange - workflow platforms such as Zapier, Power Automate, n8n and Make, or a quick curl test. For those, create an API key on the same account portal page as your OAuth client and send it on every call. OAuth client-credentials authentication remains the recommended default for server integrations.

curl -s "https://api.cdr.redeagle.tech/v1/documents?filename=report.docx&wait=true" \
  -H "X-Api-Key: $CDR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @report.docx

Create one key per platform, labelled with where it lives - then a credential that leaks, or a platform you stop using, can be revoked on its own without touching anything else. Platforms typically attach the key to every request automatically, including the cleaned-file download: the storage layer simply ignores an X-Api-Key header on the pre-signed link, so the download still works (an Authorization header there would be rejected - one of the reasons X-Api-Key is the canonical form).

Synchronous & asynchronous modes

Every submission runs through the same pipeline; you choose how to wait for it.

• Synchronous - add ?wait=true (or the header Prefer: respond-sync) to your submit call. If the document reaches a terminal state within the sync budget (45 seconds by default), you get 200 OK with the full result in one round trip. Small documents typically clean in under 3 seconds (measured July 2026 on a warm service: median 1.9 s, 95th percentile 7.0 s). The first submission after an idle period can be markedly slower, and if it exceeds the budget you get a 202 instead - so always handle the 202 path even when you ask for a synchronous response. It is a slower answer, never a failure.
• Asynchronous - submit without wait, receive 202 Accepted with a statusUrl, and poll at the suggested pollAfterSeconds cadence until the status is terminal.
• Graceful transition - a synchronous call that can't finish inside the budget (for example a large file) transitions to a normal 202 Accepted carrying the freshest state seen. Your polling code path handles it identically, so ?wait=true is always safe to send - the answer arrives by the other route, it is never a worse answer.

API endpoints

curl -s -X POST "https://api.cdr.redeagle.tech/v1/documents?wait=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 2b7e9c14-unique-per-attempt" \
  -F "file=@invoice.pdf"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "status": "pending",
  "submittedAt": "2026-07-21T14:22:31Z",
  "statusUrl": "https://api.cdr.redeagle.tech/v1/documents/a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "pollAfterSeconds": 2
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "status": "completed",
  "outcome": "cleaned",
  "modifications": ["rebuilt"],
  "submittedAt": "2026-07-21T14:22:31Z",
  "completedAt": "2026-07-21T14:22:33Z",
  "downloadUrl": "https://...",
  "downloadExpiresAt": "2026-07-22T14:22:33Z",
  "statusUrl": "https://api.cdr.redeagle.tech/v1/documents/a1b2c3d4-e5f6-7890-abcd-1234567890ab"
}

{
  "organisationId": "9f8e7d6c-5b4a-3210-fedc-0987654321ba",
  "organisationName": "Example Ltd",
  "planType": "payg",
  "status": "active",
  "monthlyAllowance": 0,
  "periodStart": "2026-07-01T00:00:00Z",
  "periodEnd": "2026-08-01T00:00:00Z",
  "periodUsedSubmissions": 42,
  "creditBalancePence": 4970,
  "pricePerDocumentPence": 15,
  "rateLimitPerMinute": 30,
  "maxFileSizeBytes": 104857600,
  "maxUploadSizeBytes": 262144000
}

Large files - the staged upload flow

Multipart submits carry files up to 100 MB. Beyond that (up to your plan ceiling - 250 MB on Pay-as-you-go and Starter, 450 MB on Growth and above), stage the file first: create an upload, PUT the bytes straight to storage, then submit by reference. The API is never in the data path for the bytes, which is what makes the larger sizes possible.

# 1. Create an upload slot
UPLOAD=$(curl -s -X POST https://api.cdr.redeagle.tech/v1/uploads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "board-pack.pdf"}')
UPLOAD_ID=$(echo "$UPLOAD" | jq -r .uploadId)
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .uploadUrl)

# 2. PUT the bytes straight to storage (no bearer token - the link is the auth)
curl -sS -X PUT "$UPLOAD_URL" \
  -H "x-ms-blob-type: BlockBlob" \
  -T board-pack.pdf

# 3. Submit by reference - same envelope, statuses and billing as any submit
curl -s -X POST https://api.cdr.redeagle.tech/v1/documents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"uploadId\": \"$UPLOAD_ID\"}" | jq

The upload envelope (201 Created)

{
  "uploadId": "u_9f2c4b1a0e8d47c6a3b5d9e1f2a4c6b8",
  "uploadUrl": "https://...",
  "method": "PUT",
  "requiredHeaders": { "x-ms-blob-type": "BlockBlob" },
  "maxSizeBytes": 471859200,
  "expiresAt": "2026-07-25T18:22:31Z"
}

• uploadUrl is a time-limited, single-file, write-only link. It accepts one file's bytes and nothing else - it cannot read, list or touch anything. Send the requiredHeaders with the PUT; the link stops working at expiresAt, and abandoned uploads are cleaned up automatically.
• maxSizeBytes is your plan's ceiling, checked when you submit by reference. An oversized file is refused with a 413 problem response carrying maxSizeBytes, and nothing is billed.
• Optional integrity check: send a Content-MD5 header with the PUT and storage verifies the bytes it received - transfer corruption becomes an immediate, unbilled 400 at upload time instead of a billed rejected/invalid_file at processing time.
• Any chunked uploader works: for multi-hundred-megabyte files over unreliable connections, tools like azcopy or the Azure SDKs can drive the same uploadUrl with retries and parallel blocks - plain curl -T is fine on a stable link.
• After submit, everything is identical to a multipart submission: the same 202 envelope, the same statuses, the same usage headers and the same Idempotency-Key support. Large files take longer to process - keep polling at pollAfterSeconds; the status endpoint's separate rate-limit budget means polling never crowds out submissions.
• Don't modify a staged file after submitting it. The submission records the file it accepted; if the bytes change between submit and processing, the document terminates rejected/invalid_file.

Idempotency key vs integrity check - which protects what?

They look similar - "why not just hash the file and use that as the key?" - but they answer different questions. The Idempotency-Key identifies an attempt: did this request already happen? The Content-MD5 identifies the bytes: did the file arrive intact? A content hash can't do the key's job, because submitting the same document twice on purpose (a nightly re-clean, the same template for two clients) is two legitimate attempts with identical bytes - only a per-attempt key can tell deliberate resubmission from an accidental retry.

Response taxonomy

Every document moves pending → processing → one of three terminal states. The distinction matters for billing:

Usage & quotas

Every accepted submission response carries live usage headers for your plan, so your integration always knows where it stands without an extra call:

The headers are part of the contract, not a best-effort extra: they are computed inside the same request that accepted the document - the very values the billing decision just used - so they ride every accepted submission and your integration can rely on them. What GET /v1/account adds is an answer on demand: check your balance whenever you want - before a large batch, on a schedule, or from a reconciliation job - without having to submit a document to find out.

When an allowance or balance runs out the API hard-stops with a structured refusal (see below) - it never silently bills beyond what you bought.

Errors & refusals

Every non-2xx response on /v1 is an RFC 9457 problem document (Content-Type: application/problem+json). Branch on the code member - it is stable and machine-readable; detail is the human-readable message and may be reworded. The type URI identifies the same code as a stable anchor. Refusal-specific fields (balance, price, period end, size ceiling) ride as extension members:

{
  "type": "https://api.cdr.redeagle.tech/docs/errors#insufficient-credit",
  "title": "Insufficient credit",
  "status": 402,
  "detail": "The organisation's prepaid credit balance is insufficient for this submission.",
  "code": "InsufficientCredit",
  "creditBalancePence": 5,
  "pricePerDocumentPence": 15,
  "helpUrl": "https://account.redeagle.tech"
}

Plan & account refusals:

Submission validation problems:

Rejection reasons (terminal rejected status - billed):

A rejection is the analysis working, delivered through the normal envelope rather than an HTTP error. The reason values are stable:

Other statuses:

Rate limits

Rate limits scale with plan size and are published in full - the same numbers your GET /v1/account response reports:

Being throttled returns a structured RateLimited refusal and is harmless - back off briefly and retry. Deliberately engineering around throttling (for example by spreading traffic across credentials) is a breach of the terms of service.

Supported file formats

Our CDR service supports a wide range of document and image formats commonly used in business environments. The following table lists all currently supported file types:

Formats returned in a different format

A few formats cannot be rebuilt in their original form. Rather than refuse them, we convert them - a viewable PDF is more use to you than a file you cannot open at all. When this happens the completed document carries "converted" in its modifications array and an outputFormat field, and the download is named with the new extension.

Everything else is returned in the format it was submitted in. ODT, RTF, WEBP and ZIP are all rebuilt in place.

Archives

A ZIP is accepted only if every file inside it is itself a supported type. One unsupported member rejects the whole archive with unsupported_file_type; one infected member rejects it with threat_detected. A clean archive comes back as a single rebuilt archive.

Code examples

Each example gets a token, sanitises a document synchronously (falling back to polling automatically), downloads the cleaned file, and shows the balance check. All were run against the live API in July 2026.

• curl
• C#
• JavaScript
• Python

# 1. Token (cache it - valid one hour)
TOKEN=$(curl -s https://identity.redeagle.tech/connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CDR_CLIENT_ID" \
  -d client_secret="$CDR_CLIENT_SECRET" \
  -d scope=cdr.api | jq -r .access_token)

# 2. Sanitise synchronously (200 = done; 202 = still processing, poll statusUrl)
curl -s -X POST "https://api.cdr.redeagle.tech/v1/documents?wait=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@invoice.pdf" | jq

# 3. Or async: submit, then poll the statusUrl the envelope gives you
RESP=$(curl -s -X POST https://api.cdr.redeagle.tech/v1/documents \
  -H "Authorization: Bearer $TOKEN" -F "file=@invoice.pdf")
STATUS_URL=$(echo "$RESP" | jq -r .statusUrl)
while curl -s -H "Authorization: Bearer $TOKEN" "$STATUS_URL" | jq -e '.status == "pending" or .status == "processing"' >/dev/null; do sleep 2; done
curl -s -H "Authorization: Bearer $TOKEN" "$STATUS_URL" | jq

# 4. Fetch the cleaned file (302 to a 24-hour link; -L follows it)
curl -sL -H "Authorization: Bearer $TOKEN" "$STATUS_URL/download" -o invoice.cleaned.pdf

# 5. Where do I stand? (live balance / allowance / period)
curl -s -H "Authorization: Bearer $TOKEN" https://api.cdr.redeagle.tech/v1/account | jq

// C# (.NET 8) - token, synchronous sanitise, poll fallback, download
using System.Net.Http.Headers;
using System.Net.Http.Json;

var http = new HttpClient();

// 1. Token (cache until expiry)
var tokenResponse = await http.PostAsync("https://identity.redeagle.tech/connect/token",
    new FormUrlEncodedContent(new Dictionary<string, string>
    {
        ["grant_type"] = "client_credentials",
        ["client_id"] = Environment.GetEnvironmentVariable("CDR_CLIENT_ID")!,
        ["client_secret"] = Environment.GetEnvironmentVariable("CDR_CLIENT_SECRET")!,
        ["scope"] = "cdr.api",
    }));
var token = (await tokenResponse.Content.ReadFromJsonAsync<TokenReply>())!.access_token;
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

// 2. Sanitise synchronously
using var form = new MultipartFormDataContent
{
    { new ByteArrayContent(await File.ReadAllBytesAsync("invoice.pdf")), "file", "invoice.pdf" }
};
var submit = await http.PostAsync("https://api.cdr.redeagle.tech/v1/documents?wait=true", form);
var doc = (await submit.Content.ReadFromJsonAsync<DocumentEnvelope>())!;

// 200 -> terminal now; 202 -> poll statusUrl until it is
while (doc.status is "pending" or "processing")
{
    await Task.Delay(TimeSpan.FromSeconds(doc.pollAfterSeconds ?? 2));
    doc = (await http.GetFromJsonAsync<DocumentEnvelope>(doc.statusUrl))!;
}

if (doc.status == "completed")
{
    // The /download endpoint 302s to a short-lived link; the bearer is
    // stripped automatically on the cross-origin redirect.
    var cleaned = await http.GetByteArrayAsync(doc.statusUrl + "/download");
    await File.WriteAllBytesAsync("invoice.cleaned.pdf", cleaned);
}
else
{
    Console.WriteLine($"{doc.status}: {doc.reason}"); // rejected (billed) or failed (auto-credited)
}

record TokenReply(string access_token);
record DocumentEnvelope(string id, string status, string? outcome, string? reason,
    string statusUrl, string? downloadUrl, int? pollAfterSeconds);

// JavaScript (Node 20+) - token, synchronous sanitise, poll fallback, download
import fs from "node:fs/promises";

const IDENTITY = "https://identity.redeagle.tech";
const API = "https://api.cdr.redeagle.tech";

// 1. Token (cache until expiry)
const tokenRes = await fetch(`${IDENTITY}/connect/token`, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.CDR_CLIENT_ID,
    client_secret: process.env.CDR_CLIENT_SECRET,
    scope: "cdr.api",
  }),
});
const { access_token } = await tokenRes.json();
const auth = { Authorization: `Bearer ${access_token}` };

// 2. Sanitise synchronously
const form = new FormData();
form.append("file", new Blob([await fs.readFile("invoice.pdf")]), "invoice.pdf");
let res = await fetch(`${API}/v1/documents?wait=true`, { method: "POST", headers: auth, body: form });
let doc = await res.json();

// 200 -> done; 202 -> poll
while (doc.status === "pending" || doc.status === "processing") {
  await new Promise(r => setTimeout(r, (doc.pollAfterSeconds ?? 2) * 1000));
  doc = await (await fetch(doc.statusUrl, { headers: auth })).json();
}

if (doc.status === "completed") {
  // The /download endpoint 302s to a short-lived link; fetch drops the
  // bearer automatically on the cross-origin redirect.
  const cleaned = await fetch(`${doc.statusUrl}/download`, { headers: auth });
  await fs.writeFile("invoice.cleaned.pdf", Buffer.from(await cleaned.arrayBuffer()));
} else {
  console.log(`${doc.status}: ${doc.reason}`); // rejected (billed) / failed (auto-credited)
}

# Python (3.10+) - token, synchronous sanitise, poll fallback, download
import os, time, requests

IDENTITY = "https://identity.redeagle.tech"
API = "https://api.cdr.redeagle.tech"

# 1. Token (cache until expiry)
token = requests.post(f"{IDENTITY}/connect/token", data={
    "grant_type": "client_credentials",
    "client_id": os.environ["CDR_CLIENT_ID"],
    "client_secret": os.environ["CDR_CLIENT_SECRET"],
    "scope": "cdr.api",
}).json()["access_token"]
auth = {"Authorization": f"Bearer {token}"}

# 2. Sanitise synchronously (200 = done; 202 = poll)
with open("invoice.pdf", "rb") as fh:
    doc = requests.post(f"{API}/v1/documents?wait=true",
                        headers=auth, files={"file": ("invoice.pdf", fh)}).json()

while doc["status"] in ("pending", "processing"):
    time.sleep(doc.get("pollAfterSeconds", 2))
    doc = requests.get(doc["statusUrl"], headers=auth).json()

if doc["status"] == "completed":
    # /download 302s to a short-lived link; requests drops the bearer on the redirect
    cleaned = requests.get(doc["statusUrl"] + "/download", headers=auth)
    open("invoice.cleaned.pdf", "wb").write(cleaned.content)
else:
    print(doc["status"], doc.get("reason"))  # rejected (billed) / failed (auto-credited)

Build with AI

The API publishes machine-readable maps of itself, so a coding assistant can integrate it without you pasting documentation around:

• https://api.cdr.redeagle.tech/llms.txt - the concise AI-facing map of the API
• https://api.cdr.redeagle.tech/llms-full.txt - the full reference, including the sharp edges and the design rationale
• https://api.cdr.redeagle.tech/v1/openapi.json - the OpenAPI specification

Or paste this prompt into your assistant and go:

Integrate the Red Eagle CDR API (base https://api.cdr.redeagle.tech/v1) into my
application. Read https://api.cdr.redeagle.tech/llms-full.txt for the full
contract first. The facts that matter:

- Auth: OAuth2 client credentials at https://identity.redeagle.tech/connect/token,
  scope cdr.api. Tokens last an hour - cache and reuse, never mint per call.
- Submit: POST /v1/documents, multipart field "file". Add ?wait=true - small
  files come back 200 completed in one round trip; a 202 means poll the
  envelope's statusUrl at its pollAfterSeconds cadence until terminal.
- Files over 100 MB: POST /v1/uploads -> PUT the bytes to uploadUrl with its
  requiredHeaders -> POST /v1/documents with {"uploadId": "..."}.
- Send an Idempotency-Key header on any submit that might be retried.
- Terminal states: "completed" (fetch via GET /v1/documents/{id}/download with
  the bearer, or use downloadUrl WITHOUT the bearer - never send both);
  "rejected" (a billed, final analysis verdict - branch on reason and surface
  threatNames to the user); "failed" (our fault, automatically credited).
- Errors are RFC 9457 problem+json: branch on the stable "code" member and
  honour Retry-After on 429s. Download links expire 24 hours after completion -
  collect cleaned files promptly.

Write idiomatic code for my stack, with tests, including the poll loop and
rejected/failed handling.

The assistant-readable files and this page describe the same contract - if you ever find them disagreeing, trust the API's own /llms.txt and tell us.

Limitations

Support

If you need assistance with the CDR API, you can:

The machine-readable spec is always at https://api.cdr.redeagle.tech/v1/openapi.json.