# Wegii data escrow API

Wegii is a **data escrow wedge service**: a neutral third party that holds a verified, independent copy of a
business's data, between the business and the software vendor that runs it. This API is how that copy gets
made, through **agentic data escrow deposits** made by a SaaS vendor's job, the business itself, or an AI agent
acting for either.

It is built for three things:

- **Any shape, any size, today.** Database dumps, Parquet, CSV, JSONL, PDFs, scans, whole folders. Objects stream
  straight to storage, are never rewritten, and large uploads can resume.
- **Agents first.** Every operation is described in [OpenAPI 3.1](/openapi.json) (also at [/api/help](/api/help)),
  exposed as [MCP tools](mcp.md), and summarised for models in [/llms.txt](/llms.txt). The API also has a
  [page for AI agents](/ai).
- **A standard that can grow.** Deposit raw data now. Add files in [WDX](wdx.md) (Wegii Data Exchange) format beside
  it as the shapes mature, and [help define them](partners.md).

## Sandbox in five minutes

No sign-up. A sandbox pair gets its own isolated space, capped at 5 GB. Use test data only.

```bash
export WEGII=https://wegii.com

# 1. Get a key and secret. The secret is shown once.
PAIR=$(curl -s -X POST $WEGII/api/v1/sandbox/keys \
  -H 'content-type: application/json' -d '{"vendorName":"Acme Practice Cloud"}')
export WEGII_KEY=$(echo "$PAIR" | jq -r .key) WEGII_SECRET=$(echo "$PAIR" | jq -r .secret)

# 2. Which escrow area does this customer's data land in, and for whom?
curl -s -X POST $WEGII/api/v1/beneficiaries/lookup -u "$WEGII_KEY:$WEGII_SECRET" \
  -H 'content-type: application/json' -d '{"email":"owner@northline.example","tenant":"acct-1042"}'

# 3. Open a deposit in that area.
DEP=$(curl -s -X POST $WEGII/api/v1/deposits -u "$WEGII_KEY:$WEGII_SECRET" \
  -H 'content-type: application/json' \
  -d '{"tenant":"acct-1042","beneficiary":{"email":"owner@northline.example"},"source":{"system":"acme-pm"}}' | jq -r .id)

# 4. Stream in whatever you have. Repeat for every file.
curl -X PUT "$WEGII/api/v1/deposits/$DEP/objects/tables/invoices.parquet" -u "$WEGII_KEY:$WEGII_SECRET" \
  -H 'X-Wegii-Shape: table:invoices' -H 'X-Wegii-Rows: 48211' -T invoices.parquet

# 5. Seal: every byte is re-verified and the deposit becomes immutable.
curl -X POST "$WEGII/api/v1/deposits/$DEP/seal" -u "$WEGII_KEY:$WEGII_SECRET"
```

From then on, send a **differential** deposit on your schedule. It holds only what changed since the last
sealed deposit, and it lands in the same area.

## Concepts

| Term | Meaning |
|---|---|
| **Key + secret** | `wgk_sbx_pk_…` / `wgk_sbx_sk_…` for sandbox, `wgk_live_…` for live. The key names your integration; the secret proves it. |
| **Tenant** | Your own stable id for the customer whose data this is |
| **Beneficiary** | The business owner who will pick the data up, sent as an email and identified by their Person Feed person hash |
| **Escrow area** | The bucket a deposit lands in: one vendor, one tenant, one beneficiary. Derived by Wegii, never chosen by the caller. |
| **Deposit** | One point-in-time delivery. `full` is a complete copy; `differential` holds changes since a sealed base. |
| **Object** | One file inside a deposit, at a path you choose. Any bytes, any size. |
| **Shape** | A label on an object: `raw`, `file`, `table:<name>`, or `wdx:<shape>@<version>` |
| **Manifest** | Optional JSON describing the source schema, row counts and field meanings, checked at seal |
| **Seal** | Re-hashes every stored object, cross-checks the manifest, and makes the deposit immutable |
| **Snapshot** | The latest sealed full deposit plus every later differential, resolved into one object list |

## Discovery for agents

No key needed:

```
GET  /llms.txt                     orientation in prose, for a model
GET  /openapi.json                 OpenAPI 3.1, generated for this host (alias: /api/help)
GET  /api/v1/mcp/tools             MCP tool manifest
POST /api/v1/mcp                   MCP Streamable HTTP endpoint
GET  /api/health                   liveness, and what is wired vs not
GET  /.well-known/ai-plugin.json   plugin manifest
GET  /api/v1/wdx/shapes            WDX draft registry
GET  /mcp/wegii-mcp.mjs            stdio MCP client for backing up local files
```

## What is built, and what is not yet

This is written down plainly so nobody builds on a promise. `GET /api/health` returns the same list, live.

| Capability | Status |
|---|---|
| Sandbox key + secret pairs, deposits, full and differential | **Built** |
| Beneficiary lookup and escrow areas | **Built** |
| Streamed uploads of any size, resumable chunked uploads | **Built** |
| Checksums on upload, re-verification at seal, manifest cross-check | **Built** |
| WDX validation, JSON Schemas, partner proposals | **Built** |
| Snapshots, object download | **Built** |
| MCP over HTTP, stdio MCP client, generated OpenAPI and llms.txt | **Built** |
| Live key pairs | Built. Issued by Wegii on request. |
| Release to the beneficiary (they sign in with Person Feed and pull their data) | Not wired. `POST /api/v1/releases` answers `501`. |
| Scheduled restore tests into a clean environment | Not wired. `501`, and seal reports `restoreTest: "not_run"`. |
| Retention clocks per record class | Not wired |
| Region-pinned object storage with customer-held keys | Not wired. Objects are stored on Wegii's API host. |

## Next

- [API reference](api.md): every endpoint, header and error
- [MCP and AI agents](mcp.md): connect Claude, Cursor or any MCP client, plus agentic backup recipes
- [WDX standard](wdx.md): the record envelope, manifest format and draft shapes
- [WDX partners](partners.md): escrow areas, files vs databases, validating and proposing shapes

Questions, or a live key pair: [sempleventures@gmail.com](mailto:sempleventures@gmail.com)