Embeds

An embed puts a CloudRaker view on your page. Your users review extracted values, correct them and approve them without a CloudRaker account. Your backend creates a short-lived embed session with your API key. Your page loads the session URL in an iframe.

The embed has three views:

In write mode, the person can edit values and approve a document. Each saved change and each approval sends a signed webhook and a message to your page.

How it works

Create a session

curl -sX POST https://api.cloudraker.com/v1/embeds \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run": { "id": "exr_01K6ZQ8X4J3M2N7P5R9T1V0W2Y" },
    "mode": "write",
    "origins": ["https://emr.partner.example"],
    "user": { "id": "clinician-4821", "name": "Dre Tremblay", "email": "[email protected]" },
    "webhook": { "id": "whe_01K6ZQ9A1B2C3D4E5F6G7H8J9K" },
    "theme": {
      "mode": "light",
      "colors": { "primary": "#0f766e", "primary-foreground": "#ffffff" },
      "radius": "8px",
      "font": "system"
    },
    "locale": "fr-ca",
    "metadata": { "encounterId": "enc_77" },
    "ttl": 3600
  }'

The response is 201:

{
  "object": "embed_session",
  "id": "ems_01K6ZQB3C4D5E6F7G8H9J0K1M2",
  "view": "review",
  "mode": "write",
  "url": "https://embed.cloudraker.com/embed/ems_01K6ZQB3C4D5E6F7G8H9J0K1M2#token=eyJhbGciOiJIUzI1NiJ9…",
  "run": { "id": "exr_01K6ZQ8X4J3M2N7P5R9T1V0W2Y" },
  "documents": ["file_01K6ZQ7W3H2G1F0E9D8C7B6A5Z"],
  "expiresAt": "2026-09-29T15:04:05.000Z",
  "createdAt": "2026-09-29T14:04:05.000Z"
}

A transcript session binds one file:

curl -sX POST https://api.cloudraker.com/v1/embeds \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "view": "transcript", "file": { "id": "file_01K6ZQ7W3H2G1F0E9D8C7B6A5Z" }, "origins": ["https://emr.partner.example"] }'

Put the iframe on your page

<iframe
  src="{session.url}"
  title="CloudRaker review"
  allow="clipboard-write"
  referrerpolicy="no-referrer"
  style="width: 100%; height: 720px; border: 0"
></iframe>

• Your page sets the size. The embed fills the frame.
• allow="clipboard-write" lets the person copy values.
• The page must be one of the session origins. When a page from another origin frames the embed, the embed refuses to render and sends no message.
• The embed removes the token from its address bar after it loads. A reload of the iframe keeps the session.

If you sandbox the iframe, use exactly these flags:

sandbox="allow-scripts allow-same-origin allow-forms allow-popups"

A sandbox without allow-same-origin gives the frame an opaque origin. The embed does not support that.

Messages to your page

The embed posts messages to window.parent. It sends them only to an origin in the session origins, never to *. It ignores all messages that your page sends to it.

type EmbedMessage = {
  source: "cloudraker-embed";
  version: 1;
  trusted: false;
  sessionId: string; // ems_…
  type: "ready" | "document_saved" | "document_approved" | "error";
  payload:
    | { view: "review" | "transcript" | "document"; mode: "read" | "write" } // ready
    | { fileId: string; rev: number; changedKeys: string[]; document: Document } // document_saved, document_approved
    | { code: "session_expired" | "review_closed" | "conflict" | "rate_limited" | "load_failed" }; // error
};

document has the same shape as a document in GET /v1/runs/:id: fileId, name, value and citations.

Always check the origin and the session id before you use a message:

const embedOrigin = new URL(session.url).origin; // https://embed.cloudraker.com
window.addEventListener("message", (event) => {
  if (event.origin !== embedOrigin) return;
  const msg = event.data;
  if (msg?.source !== "cloudraker-embed" || msg.sessionId !== session.id) return;
  if (msg.type === "document_approved") closeReviewModal();
});

In read mode, the embed posts only ready and error.

Webhooks

A write session sends two event types:

A save with no change sends nothing. The events go to the session webhook and to every saved endpoint of your organization that subscribes to the type, or to all types. Each endpoint gets one delivery per event.

{
  "eventId": "9b2f6c1e-4a7d-43b0-8c55-0e1f2a3b4c5d",
  "type": "embed.document_approved",
  "processingId": "exr_01K6ZQ8X4J3M2N7P5R9T1V0W2Y",
  "occurredAt": "2026-09-29T14:12:30.000Z",
  "data": {
    "embedSessionId": "ems_01K6ZQB3C4D5E6F7G8H9J0K1M2",
    "runId": "exr_01K6ZQ8X4J3M2N7P5R9T1V0W2Y",
    "fileId": "file_01K6ZQ7W3H2G1F0E9D8C7B6A5Z",
    "rev": 1,
    "changedKeys": [],
    "document": {
      "fileId": "file_01K6ZQ7W3H2G1F0E9D8C7B6A5Z",
      "name": "call.m4a",
      "value": { "reason": "Toux", "diagnosis": "Bronchite aiguë" },
      "citations": { "reason": [{ "fileId": "file_01K6ZQ7W3H2G1F0E9D8C7B6A5Z", "timecodeStart": 12.4, "timecodeEnd": 15.1, "timecode": 12.4, "text": "…", "confidence": 4 }] }
    },
    "user": { "id": "clinician-4821", "name": "Dre Tremblay", "verified": false },
    "metadata": { "encounterId": "enc_77" }
  }
}

• document is the full document after the change, not a diff. changedKeys lists the fields that changed.
• An edited field loses its citation.
• user is absent when the session has no user. metadata is absent when the session has none.
• eventId is stable across retries. A save and an approval at the same rev have different ids. Dedupe on eventId.
• CloudRaker does not store an approval state. Record the approval on your side when you receive the event.

Verify every delivery. Embed events use the same signature as all other events: the x-rk1-signature ES256 JWT, checked against GET /v1/webhooks/jwks.json, with iss rakerone-process and a bodySha256 claim for the raw body. The webhooks page has the steps and sample verifiers. In short:

const { payload } = await jwtVerify(req.headers["x-rk1-signature"], JWKS, {
  issuer: "rakerone-process",
  algorithms: ["ES256"],
});
if (createHash("sha256").update(rawBody).digest("base64url") !== payload.bodySha256) {
  throw new Error("body digest mismatch");
}

Save conflicts (rev)

Each document has a revision number, rev. It starts at 0. Each saved change adds 1.

The embed sends the rev it loaded with each save. If the document changed after the page loaded, the save fails. For example, a colleague edited it in the CloudRaker app, or in another session. The embed then:

• shows the banner “This document changed after you opened it.” with a Reload button. Reload loads the current values and drops the local edits.
• posts an error message with code conflict.

A stale approval fails in the same way. Events can arrive out of order. Use rev to keep the newest version of each document.

Themes

Send theme to match your app. All keys are optional. An unknown key or a value that does not match its pattern is a 400.

The color keys are:

background, foreground, card, card-foreground, popover, popover-foreground, primary, primary-foreground, secondary, secondary-foreground, muted, muted-foreground, accent, accent-foreground, destructive, border, input, ring.

The patterns accept only plain values. Other CSS (url(, var(, ;, { and comments) always fails. The confidence rating colors do not change with the theme.

Identity

user is the person who uses the view, as your system knows them: { id, name, email? }.

• CloudRaker does not verify it. It stores it as you send it.
• The audit log names the person as ext:<id> with the given name, and marks the identity as not verified.
• Webhooks carry { id, name, verified: false }.
• The email stays with CloudRaker. No webhook, message or audit event contains it.

Revoke a session

curl -sX DELETE https://api.cloudraker.com/v1/embeds/ems_01K6ZQB3C4D5E6F7G8H9J0K1M2 \
  -H "Authorization: Bearer $CLOUDRAKER_API_KEY"

The response is 204, also for a session that is already revoked. The iframe stops working on its next request. There is no route to list or read sessions, so store the id when you create a session.

Limits

Origin onboarding

The embed shows only on pages that CloudRaker allows to frame it. Before you go live, send the exact origins of your pages (for example https://emr.partner.example) to your account team. CloudRaker adds them to the allowed list. The origins of each session must be on that list.

On test environments, http://localhost and http://127.0.0.1 on any port are allowed.

Errors

Where to go next