Skip to navigation

Agent-assisted integration

Set up an embedded workspace and webhook receiver with your coding agent.

Hand it to your agent

Use the instructions below to embed SpreadSpace in your loan page and receive approved figures in your backend. When an analyst finalizes a spread, SpreadSpace saves an immutable snapshot and sends spread.finalized. Your receiver retrieves the snapshot by ID and stores it in your database. A later spread.reopened event lets your application mark the figures as under revision.

1

Save the skill

Copy the SKILL.md block below to .claude/skills/spreadspace-integration/SKILL.md (Claude Code), or paste it into AGENTS.md or your rules file (Cursor, Codex, and similar tools). It covers the embed and webhook integration.

2

Add the standing rules

Append the CLAUDE.md block to your own CLAUDE.md / AGENTS.md, so the rules hold on every session rather than only the one that writes the code.

3

Put the API keys in your environment

Two key shapes, both from Settings → Live API. For the receiver, a key from the Backend preset, which holds webhooks:read, webhooks:write and spreads:read, as SPREADSPACE_API_KEY. For the mint, a key from the Embed preset, which holds embed:write and the writes a session may carry, with the origin of your loan page under Allowed origins, as SPREADSPACE_EMBED_API_KEY. One key can hold both: start from the Embed preset, add webhooks:read, webhooks:write and spreads:read, and set both variables to it. Test-mode keys (ss_test_…) use seeded loans and sample extraction results at no charge. Use live mode to process your own documents.

4

Give it the prompt

Integrate SpreadSpace, both legs. Embed: add a server endpoint that mints a
SpreadSpace handle for the loan on the page and the signed-in user, and
render the SpreadSpace workspace on our loan page from it. Receive: handle
spread.finalized, read the snapshot it names by id, persist its figures
against our loan record, show them on our loan page, and handle
spread.reopened. The keys are SPREADSPACE_API_KEY and
SPREADSPACE_EMBED_API_KEY. Follow the
spreadspace-integration skill.

Your agent can also read this page directly at https://docs.spreadspace.app/get-started/agent-assisted-integration.md. Every page here has a .md twin, and the index is at /llms.txt.

SKILL.md

Save this as .claude/skills/spreadspace-integration/SKILL.md, or paste it into your agent’s rules file.

SKILL.md

The standing rules

Add this block to your own CLAUDE.md / AGENTS.md, so the rules hold on every session, not just the one that writes the code.

CLAUDE.md
# SpreadSpace integration
Follow the `spreadspace-integration` skill for anything touching SpreadSpace:
embedding the workspace on our loan page, receiving `spread.finalized`,
persisting the frozen figures, rendering them.
Standing rules:
1. Never log the API key or a `whsec_…` signing secret, not in errors and not in traces.
2. The webhook receiver reads the **raw** request body bytes. Re-serialized JSON
   never verifies.
3. Dedupe on the event id (`SpreadSpace-Event-Id`, equal to the body's `id`).
4. Persist snapshots **whole**, upserted on `snapshot_id`, which is unique.
5. The by-id snapshot read is the source of truth. Never rebuild figures from the
   event. The event is a pointer, not the numbers.
6. The API key and the `embed_token` never reach the browser. The page gets a
   `signed_url` and nothing else; the SDK client and the key stay on the
   server.
7. Mint a handle per page load and per refresh, at the moment the page asks.
   Never cache, reuse or pre-mint a handle or a `signed_url`; a handle is
   exchanged once.
8. `external_user_id` comes from our own server session, never from the request
   body or anything else the browser sends.
9. Return the `signed_url` unchanged. The component loads it verbatim.
10. Name `scopes` explicitly on every mint: `documents:read`, `extractions:read`
    and `spreads:read`, plus `spreads:write` only where the analyst may
    finalize and `documents:write` only where they may upload.
11. Register the origin of every page that holds the frame in the Embed key's
    allowed origins before that page ships.
Docs: <https://docs.spreadspace.app/llms.txt> is the index, and every page has a
`.md` version (append `.md` to any docs URL) built for agents to read directly.

What you’ll have

  • The workspace on your loan page: your server mints a handle per load, your page renders it with <SpreadSpaceEmbed>, and refresh is handled. The API key stays on your server, and the session token stays inside the iframe.
  • Approved figures in your database: spread.finalized triggers snapshot retrieval and storage, keyed by snapshot_id.
  • Reopen handled: spread.reopened marks that copy under revision until the next finalize arrives with a higher version.
  • “Finalized by” from your own users table, joined on finalized_by_external_user_id, the id your server named when it minted the handle.
  • Replay and rotation handled: a redelivery is a no-op, and a rotated secret verifies through its 24-hour grace window.
  • Stored results on your loan page: display the saved figures from your database.

Not covered here: hosting the frame without the React component (the React embed SDK page describes the protocol module for a hand-rolled frame), and production hardening on your side (secret storage, alerting, your own retries).

Up next

API integration guide

Receive finalized spreads and store the approved figures in your application.

Embed integration guide

Add the workspace to your application and configure sessions and permissions.

Webhooks

Every event, the envelope, delivery, replay and rotation.

Spreads and attributes

The snapshot lifecycle, the payload and the manifest, key by key.

Attribute catalog

Every attribute and ratio name, its label, unit and basis.

Embed

Render the workspace inside your own product so the Finalize click happens there.