Edit URL (embedded viewer)

{
  "run_id": "run_01HXYZ",
  "download_url": "https://backend.overtenai.com/api/v1/runs/run_01HXYZ/download",
  "edit_url":     "https://backend.overtenai.com/api/v1/edit/run_01HXYZ?token=...",
  ...
}

​

download_url vs edit_url — when to use which

​

How it works end-to-end

  Your app                 Overten API                 Overten storage
  ────────                 ───────────                 ───────────────
     │
     │ 1. Submit prompt
     │────────────────────────>│
     │                         │   run agent, persist file
     │                         │─────────────────────────────>│
     │<──── download_url       │
     │      edit_url(token) ───│
     │
     │ 2. <iframe src={edit_url}>
     │─────────────────────────┐
     │                         │  validate token
     │                         │  load file from storage
     │                         │<────────────────────────────│
     │   3. Rendered document  │
     │<────────────────────────│

1. You call POST /excel/generate (or word/slides), get back edit_url.
2. You embed that URL in an iframe in your UI.
3. Overten validates the token, loads the run’s file from storage, and streams a rendering of the document into the iframe.
4. Every subsequent user action (scroll, click, zoom) stays between the browser and Overten — your app never sees the content, never handles bytes, never runs a viewer itself.

​

Token semantics

• Opaque — a random string, not a JWT. Generated by Overten, validated by Overten. Don’t try to parse it client-side.
• Scoped to one run + your org — if someone copy-pastes the URL into another app, the token still only unlocks this document for your org.
• Short-lived, sliding — 15 minutes from the last user activity. Active viewer sessions refresh the TTL automatically; idle sessions (user closed the tab) expire on their own.
• No explicit revoke endpoint today. The short sliding TTL is the mitigation. If you suspect a leak before a token has expired naturally, contact support with the run_id and we can invalidate on our side.

​

Basic embed

<iframe
  src="{{ run.edit_url }}"
  width="100%"
  height="800"
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms"
></iframe>

function DocumentViewer({ run }) {
  return (
    <iframe
      src={run.edit_url}
      title="Document viewer"
      style={{ width: "100%", height: "100vh", border: 0 }}
      allow="clipboard-read; clipboard-write"
    />
  );
}

​

How edits land

1. Direct in-iframe edits. The user types, changes a cell, rewrites a paragraph, moves a slide. Edits auto-save to the run’s artifact (same storage location download_url points at). The next fetch serves the updated bytes.
2. Agent-driven edits via API. Call the relevant generate endpoint with the original run_id and a new prompt; the agent picks up whatever state is current (including the user’s in-iframe edits) and applies the change:
   resp = requests.post(
       f"{API}/excel/generate",
       headers=headers,
       json={
           "run_id": "run_01HXYZ",
           "prompt": "Apply a % YoY column to the Summary sheet "
                     "and extend the headcount chart through Q4.",
       },
   )
   

​

Getting a fresh URL after expiry

curl -X POST "https://backend.overtenai.com/api/v1/excel/generate" \
  -H "X-API-Key: $OVERTEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run_01HXYZ",
    "prompt": "(no change — just reopening the session)"
  }'

​

What edit_url is NOT

• Not a shareable public link. Tokens are scoped to one viewer session. Don’t email an edit_url — it’ll work for 15 minutes, then stop, and before then it unlocks your org’s run to whoever clicked.
• Not a download. The iframe renders the document live; bytes never land on the user’s disk via this route. For downloads, use download_url.
• Not a programmatic write API. In-iframe edits work for human users, but your server-side code should use the generate endpoint with run_id to apply structured changes — that’s auditable, has a ledger row, and doesn’t require a browser.
• Not a hosted Office install. Your end-user doesn’t need Excel / Word / PowerPoint locally. The viewer runs entirely in the browser.

​

Security notes

• Mint per viewer. Don’t store one edit_url server-side and serve it to multiple users. The token is meant for one session — each user should get a freshly-minted URL.
• Strip tokens from logs / analytics. Drop the token query param before recording page URLs in your observability tools.
• Restrict frame ancestors. If you serve edit_url in an <iframe>, set a Content-Security-Policy on your parent page that limits which origins can frame your dashboard, so an attacker can’t frame your app and read the iframe’s state via JS.
• Prefer your own domain for the parent page. The token is only meaningful in-browser; someone who captures the URL during a session and opens it from another host still has to get past the sliding TTL.

​

White-label / custom branding

• Use download_url and render the file with your own tooling (Google Drive viewer, OnlyOffice, SheetJS, native Office apps).
• Or fetch the file bytes server-side and hand them to your preferred renderer.