# Wegii

> 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 its software vendor. This API lets AI
> agents and SaaS vendors make agentic data escrow deposits, and help define WDX, the Wegii
> Data Exchange format.

Any bytes, any format, any size. Store originals unchanged; WDX-mapped files sit beside them.

## Discovery (no key needed)

- OpenAPI 3.1: http://wegii.com/openapi.json (alias: http://wegii.com/api/help)
- MCP endpoint (Streamable HTTP, JSON-RPC 2.0): http://wegii.com/api/v1/mcp
- MCP tool manifest: http://wegii.com/api/v1/mcp/tools
- Plain JSON tool calls: POST http://wegii.com/api/v1/mcp/call {"name", "arguments"}
- Health, mode and what is wired: http://wegii.com/api/health
- Plugin manifest: http://wegii.com/.well-known/ai-plugin.json
- WDX registry: http://wegii.com/api/v1/wdx/shapes
- Stdio MCP client for local files (Node 18+, no dependencies): http://wegii.com/mcp/wegii-mcp.mjs

## Docs (plain markdown)

- [Overview and sandbox walkthrough](http://wegii.com/docs/index.md)
- [API reference](http://wegii.com/docs/api.md)
- [MCP and AI agents](http://wegii.com/docs/mcp.md)
- [WDX standard](http://wegii.com/docs/wdx.md)
- [WDX partners: validate mappings, propose shapes](http://wegii.com/docs/partners.md)
- Human landing page for agents: http://wegii.com/ai

## Credentials

Every call past discovery sends a key and a secret:
    X-Wegii-Key: wgk_…_pk_…      names the integration
    X-Wegii-Secret: wgk_…_sk_…   proves it (or HTTP Basic key:secret)
- Sandbox key, self-serve, test data only: POST http://wegii.com/api/v1/sandbox/keys
- Live keys are issued by Wegii: sempleventures@gmail.com
- Call GET /api/v1/capabilities once per session: identity, mode, limits, wired vs not wired.

## Agentic deposit in five calls

1. POST /api/v1/deposits {"tenant": "<your customer id>"}
2. PUT /api/v1/deposits/{id}/objects/{path}   (stream any file; repeat)
3. PUT /api/v1/deposits/{id}/manifest          (optional: schema, row counts, meanings)
4. POST /api/v1/deposits/{id}/objects/{path}/validate   (optional: check a WDX JSONL file)
5. POST /api/v1/deposits/{id}/seal             (re-verifies every byte; permanent)

Later deposits: {"kind": "differential", "baseDepositId": "<last sealed>"}.

## MCP tools

- wegii_capabilities: Who this key is, its mode (sandbox or live), limits and bytes used.
- wegii_lookup_beneficiary: Which escrow area does this customer's data land in, and for whom? Send the business owner's email (never a hash); get back their Person Feed personHash, the areaId for a tenant, and the areas this vendor already holds for them.
- wegii_create_deposit: Open a deposit for one tenant (your customer).
- wegii_put_object: Store one object in an open deposit.
- wegii_put_manifest: Attach a manifest describing the deposit: source schema, tables, columns, row counts, field semantics, WDX mappings.
- wegii_seal_deposit: Verify every stored byte against its checksum, cross-check the manifest, and make the deposit immutable.
- wegii_list_deposits: List deposits for this key, newest first.
- wegii_get_deposit: One deposit with its full object index, tombstones and verification result.
- wegii_get_object: Read an object back (up to 1 MB per call; use offset for more).
- wegii_delete_object: Remove an object from an open deposit.
- wegii_snapshot: Point-in-time view of a tenant: the latest sealed full deposit plus every later sealed differential, resolved to one object list.
- wegii_wdx_shapes: The WDX draft standard: record envelope, rules and the current shape registry.
- wegii_wdx_shape_schema: JSON Schema (2020-12) for one WDX shape's full record envelope.
- wegii_wdx_validate: Validate up to 1,000 WDX records before uploading them.
- wegii_validate_object: Validate an uploaded WDX JSONL object line by line, streaming, without downloading it.
- wegii_wdx_propose: Propose a change to WDX: a new shape, a new field, a field change or a new version.
- wegii_wdx_proposals: List WDX proposals, newest first — check before proposing something that already exists.

## WDX: Wegii Data Exchange (spec 0-draft)

- party@0 (draft): A person or organisation: customer, supplier, patient, employee, member.
- ledger-entry@0 (draft): One side of a balanced journal. Entries sharing a journalId must net to zero per currency.
- document@0 (draft): A business document: invoice, bill, quote, receipt, contract, note or attachment.
- appointment@0 (draft): A scheduled block of time with people and resources.
- asset@0 (draft): Something owned, serviced or tracked: equipment, vehicle, property, animal, stock item.
- work-order@0 (draft): A job: repair, service visit, treatment plan, project task.

Rules:
- Raw first: upload the original export unchanged; WDX files sit beside it, never instead of it.
- Omit what you do not know. A missing field is 'unknown'; null, 0 or '' are claims.
- Money is { value: "12.50", currency: "USD" }. Timestamps are RFC 3339 with an offset.
- Anything unmapped goes in extra. New shape fields are promoted from what vendors keep putting there.
- A breaking change is a new version (party@1). Readers must ignore fields they do not recognise.

Partners shape the standard through the API:
- GET  /api/v1/wdx/shapes/{shape}@{version}   JSON Schema 2020-12 for one shape
- POST /api/v1/wdx/validate                   check records before uploading
- POST /api/v1/wdx/proposals                  propose a shape, a field, or a change
- GET  /api/v1/wdx/proposals                  what has been proposed and its status

## Honesty contract

- Unknown is omitted, never null, zero or empty.
- A seal attests to bytes re-read from storage, not to what an upload claimed.
- An email in a request body is a claim, not an identity. Beneficiaries are unverified until they sign in.
- Paths that are not wired return 501 not_implemented with detail.blocker. Do not retry them.
- Errors carry {error, message, docs}; the message is written to be relayed to a person.
- Sandbox keys are for test data only.