# Oblivion Documentation - Full Content

> Complete documentation content for AI ingestion. This file contains all documentation in a single, structured format.


## User Guide


### Overview

URL: /docs/user-guide/overview

# Oblivion — User Guide

> **Beta — experimental software.** Use at your own risk. Approvals are your responsibility; this is not legal or security advice.

Oblivion is a private cleanup agent that removes your personal information from third-party data brokers **without asking you to give it to another middleman**. Your sensitive details stay encrypted in your browser; the server stores only encrypted blobs and redacted metadata. We discover people-search listings, draft broker opt-outs, run breach checks, and suppress search results — **nothing sends until you approve** the exact disclosure.

**Building an app?** [Partner API](/docs/developers/partner-api) · **Choosing a template?** [Templates](/docs/user-guide/templates)

Use the **agent panel** (right on desktop, bottom on mobile). Tap **Continue** when prompted.

```mermaid
flowchart TB
  Start[Start case + vault] --> Discover[Find exposures]
  Discover --> Review[Confirm matches]
  Review --> Approve[Approve disclosure]
  Approve --> Execute[Record or send]
  Execute --> Recheck[Schedule recheck]
```

---

## Start

1. **Start** → name, template, **Start cleanup**
2. Or type one line in the agent panel
3. Dashboard opens with your route running

Your browser stores a private **case access token** when a case is created. It is required for all server requests on that case and stays in local storage on this device — there is no email/password account.

### Two keys (wallet + case token)

| Credential | What it does |
|------------|--------------|
| **Wallet** | Credits, subscription, and per-case activation billing |
| **Case access token** | Authorizes `/api/*` for one case only |

Connect wallet to pay; keep the case token (or a **recovery kit** export) to reopen the case on another browser. After wallet connect, linked cases appear in the sidebar — you still need the token from your kit to access them.

**Free preview:** On the landing page, enter your name for a limited broker check (no wallet). **Start full cleanup** creates a case, requires wallet + activation, and runs Venice-scored discovery.

## Review

1. **Overview** — **Confirm** or **Not me** on each listing
2. Paste URLs or **Search again** if needed
3. **Continue** until approvals appear

## Approve

1. Open **Approvals** (or **Continue**)
2. Read destination, data categories, purpose
3. **Approve** only if it matches your intent — nothing sends without this

---

## Controls

| Button | Does |
|--------|------|
| **Continue** | Next safe step |
| Agent input | `run`, `status`, `explain` |

Sidebar: Overview · Approvals · Settings · Cases

## Credits and wallet

Starting a cleanup requires a **connected wallet** and a **paid credit purchase for that case** (Starter pack — 500 credits / $5 USDC — or Monitor subscription — 1,200 credits/month / $10 USDC). Until payment settles for the case, the dashboard stays on onboarding and workflow APIs return `case-activation-required`.

Metered features then debit the same wallet balance:

- **Full broker discovery** — 15 credits per sweep (Venice-scored)
- **Venice AI** (agent chat, classify, draft)
- **Live operator email relay** — 25 credits per send when enabled
- **x402 / Smart Account demos** — USDC on Base Sepolia

Monitor subscribers: monthly credit refill and new cases auto-activate for that wallet.

Buy or manage credits in **Settings → Payment rails**. See [Pricing](/docs/pricing).

---

## Stuck?

| Issue | Fix |
|-------|-----|
| No dashboard | Connect wallet, buy credits for this case, then **Start cleanup** |
| Blocked | Check **Approvals** |
| Wrong case | **Cases** → new or switch |
| Venice blocked | Connect wallet + buy credits in **Payment rails** |

More answers: [FAQ](/docs/faq)

---


### Templates

URL: /docs/user-guide/templates

# Cleanup Templates

Pick the goal that matches your cleanup. Each template asks for different identifiers and follows the same supervised workflow: discover, review, approve, then record or send.

[User guide](/docs/user-guide/overview)

```mermaid
flowchart TB
  subgraph intake["1 · Intake"]
    A[Encrypt in browser] --> B[Trust check]
  end

  subgraph discover["2 · Discover"]
    B --> C[Find exposures]
    C --> D{Review matches?}
    D -->|yes| E[Confirm links]
    D -->|skip| F[Plan removal]
    E --> F
  end

  subgraph act["3 · Act"]
    F --> G[Draft request]
    G --> H[You approve]
    H --> I[Record or send]
    I --> J[Schedule recheck]
  end
```

---

## Pick a template

| Goal | Template | Requirements | What you provide | Review each match? |
|------|----------|--------------|------------------|-------------------|
| Remove people-search listings | People-search cleanup | US, EU, or UK | Name, email, city/state | Yes |
| Hide Google results | Search suppression | US, EU, or UK | Name, email | No |
| California DROP request | California DROP | US case + **California residency** | Name, email, address | No |
| EU/UK erasure | GDPR erasure | **EU or UK** case | Name, email | No |
| Breach check | Breach exposure | US, EU, or UK | Email | No |
| Urgent address or relative exposure | High-risk safety | US, EU, or UK | Name, address, relative | Yes |
| Copied content takedown | Content takedown | US, EU, or UK; you control the original work | Name, email, URL, work reference | Yes |

**Requirements** are set when you start a case (jurisdiction) and by what the official route allows:

- **California DROP** — only for people who live in California. Oblivion guides and tracks the flow; you submit on the [official DROP site](https://privacy.ca.gov/drop/).
- **GDPR erasure** — only when your case jurisdiction is EU or UK (not US-only).
- **Content takedown** — you must be the rights holder or authorized to act for the work being copied.

Integrators: preset IDs and API details are in the [Partner API](/docs/developers/partner-api).

---

## What happens on every template

| Phase | What you experience |
|-------|---------------------|
| **Encrypt** | Identifiers stay in your browser vault; the server sees ciphertext and redacted labels only |
| **Trust check** | Production deployments verify hardware attestation before sensitive live sends |
| **Discover** | Oblivion finds candidate listings, breach signals, or guidance URLs |
| **Review** | You confirm or reject each match (some templates skip this) |
| **Plan removal** | Official opt-out, suppression, or rights paths are identified |
| **Draft** | Request text is prepared; AI can refine if you have credits |
| **Approve** | You read each disclosure card — nothing sends without your confirmation |
| **Execute** | Default is a logged practice run with handoff steps; live sends need trust verification + approval |
| **Follow up** | Replies are tracked; recheck is scheduled (typically 14–90 days) |
| **Complete** | Case finishes; you can return later if listings reappear |

**Autonomy:** Default mode shows one approval per destination. High-autonomy batches cards — you still approve each batch explicitly.

---

## What each template focuses on

- **People-search cleanup** — broker listings, opt-out paths, California DROP guidance where relevant
- **Search suppression** — Google removal planning; you complete submission on Google’s site
- **California DROP** — California-resident guided workflow on the official state registry (you complete submission)
- **GDPR erasure** — erasure templates plus search suppression planning
- **Breach exposure** — email breach check; password check uses prefix-only ranges, never full passwords
- **High-risk safety** — same discovery family as people-search with stricter match review
- **Content takedown** — DMCA-style drafts and platform abuse paths

---

## Never automatic

- Raw identifiers leaving the vault without your approval
- Live email or broker submission without production trust verification
- Passwords, SSNs, or breach-dump searches
- Broad consent — each action names destination, categories, purpose, and expiry

---

## Practice run vs live send

| Mode | What it means |
|------|----------------|
| **Practice run** (default) | Actions are logged with clear handoff instructions for you to complete |
| **Live send** | After you approve, Oblivion may transmit only the approved data — requires production trust verification |

[Open Oblivion](https://oblivion.phantasy.bot)

---


### Pricing

URL: /docs/pricing

# Pricing

Oblivion uses a **wallet credit balance** — not per-case chat caps. Pay with **USDC on Base** via x402 and scoped payment permissions. Credits fund Venice AI and live operator email relay. **Every disclosure still needs your explicit approval.**

```mermaid
flowchart TB
  Wallet[Connect wallet] --> Buy[Buy with USDC]
  Buy --> Starter["Starter pack: $5 → 500 credits"]
  Buy --> Monitor["Monitor: $10/mo → 1200 credits"]
  Starter --> Balance[Wallet balance]
  Monitor --> Balance
  Balance --> Venice["Venice AI: 1 credit / 100 tokens"]
  Balance --> Email["Email relay: 25 credits"]
  Balance --> Approve[You approve each send]
```

[Partner API billing](/docs/developers/partner-api) uses a **separate** partner credit pool — not wallet credits.

---

## Products

| Product | Price | Credits | API |
|---------|-------|---------|-----|
| **Starter pack** (`credit-starter`) | **$5 USDC** | **500** (one-time) | `POST /api/credits/purchase` |
| **Monitor** (`credit-monitor`) | **$10 USDC/mo** | **1,200** (monthly refill) | `POST /api/credits/monitor` |

Buy in the app: **Settings → Payment rails**. A scoped payment permission is required before settlement.

---

## What credits buy

| Use | Cost (default) |
|-----|----------------|
| Full broker discovery sweep | 15 credits per run |
| Venice agent chat | 1 credit per 100 tokens (minimum 1) |
| Venice classify / draft / review | Same token metering |
| Live operator email relay | 25 credits per send |

**Token budget** scales with balance (roughly 120–4,000 max tokens per request). Usage is metered until credits run out — there are no fixed per-plan chat caps.

**Per-case activation** is required before workflow APIs run (preset, discover, agent). Pay once per case with Starter, or subscribe to Monitor — an active subscription auto-activates new cases for that wallet. The landing **preview** (limited broker check, no Venice scoring) is free and does not create a case.

---

## How it works

1. Connect wallet (sidebar)
2. Open **Settings → Payment rails** → buy Starter pack or subscribe to Monitor
3. USDC settles via x402 → credits land on your wallet balance
4. Venice and live relay debit credits per use
5. Approvals still gate every external disclosure

---

## FAQ

Billing-specific questions are summarized here. For product, privacy, approvals, and troubleshooting, see the full [FAQ](/docs/faq).

**Switch later?** Settings → Payment rails — Starter top-up or Monitor subscription.

**Bypass approvals?** No — credits fund AI and relay capacity only.

**Partner integrations?** See [Partner API](/docs/developers/partner-api) — separate metered pool, no wallet required.

**Running your own server?** See [SECURITY.md](https://github.com/thomasjvu/oblivion/blob/main/SECURITY.md) and [README](https://github.com/thomasjvu/oblivion/blob/main/README.md) for operator configuration.

---

## How Oblivion compares

Oblivion is a **supervised cleanup agent** — not a traditional “set and forget” data-broker subscription. You stay in the loop: identifiers live in a **browser vault**, and **every disclosure requires explicit approval**. Wallet credits fund per-case activation, full Venice-scored discovery, AI, and live email relay. A free landing preview shows sample broker hits before you pay.

Competitor pricing and features below are from **public listings** (June 2026). Promotional coupons and regional offers change often — verify on each vendor’s site before buying.

### Starting price

| Service | Listed starting price | Billing model |
|---------|----------------------|---------------|
| **Oblivion** | **$0** (limited preview) · **$5** Starter pack · **$10/mo** Monitor | Per-case activation + metered credits; free preview before signup |
| [Optery](https://www.optery.com/) | ~$3.99/mo | Subscription |
| [Incogni](https://incogni.com/) | ~$7.99/mo | Subscription |
| [DeleteMe](https://joindeleteme.com/) | ~$8.71/mo | Subscription |
| [Aura](https://www.aura.com/) | ~$12/mo | Subscription |
| [Kanary](https://www.kanary.com/) | ~$14.99/mo | Subscription |
| [Privacy Bee](https://privacybee.com/) | ~$197/yr (~$16/mo) | Annual subscription |

### Feature comparison

| | **Oblivion** | Incogni | DeleteMe | Optery | Aura | Kanary |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| People-search / broker cleanup | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Recurring / scheduled rechecks | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| **Explicit approval before each send** | **✓** | — | — | — | — | — |
| **Identifiers encrypted in browser vault** | **✓** | — | — | — | — | — |
| Server stores only ciphertext + redacted metadata | ✓ | — | — | — | — | — |
| Manual removal requests | ✓ | ✓ | ✓ | ✓ | — | ✓ |
| Progress / case timeline | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Open-source core + agent skill | ✓ | — | — | — | — | — |
| Partner / embed API | ✓ | — | — | — | — | — |
| Hardware attestation before sensitive live sends | ✓ | — | — | — | — | — |
| Core workflow without subscription | ✓ | — | — | — | — | — |
| Wide broker network (150+ sites) | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| Identity / credit monitoring bundle | — | — | — | — | ✓ | — |
| Phishing / spam protection suite | — | ✓ | — | — | ✓ | — |
| Family plan | — | ✓ | ✓ | — | ✓ | ✓ |
| Money-back guarantee | — | ✓ | — | ✓ | ✓ | ✓ |
| 24/7 phone support | — | ✓ | ✓ | — | ✓ | — |
| Native mobile app | — | — | — | — | ✓ | — |

**Legend:** ✓ = marketed core feature · — = not a primary focus or not advertised

### When Oblivion fits

- You want **control and visibility** — nothing leaves without your sign-off on the exact disclosure.
- You prefer **local encryption** over handing identifiers to another company’s cloud vault.
- You may only need **occasional cleanup** (credits or free practice runs) instead of an always-on subscription.
- You’re building a **product** and need a [Partner API](/docs/developers/partner-api) with the same policy gates.

### When a subscription service may fit better

- You want a **fully managed, hands-off** broker-removal service with a large pre-negotiated broker list.
- You need **family coverage**, **identity theft insurance**, or **credit monitoring** in one bundle.
- You expect **24/7 human support** and formal money-back guarantees.

---

[Open Oblivion](https://oblivion.phantasy.bot)

---


### FAQ

URL: /docs/faq

# FAQ

Quick answers about Oblivion — the supervised cleanup agent, browser vault, approvals, credits, and how we differ from subscription removal services.

**New here?** [User guide overview](/docs/user-guide/overview) · [Pricing](/docs/pricing) · [Open app](https://oblivion.phantasy.bot)

---

## General

### What is Oblivion?

Oblivion is a **supervised cleanup agent** for people-search listings, breach awareness, and search suppression. It discovers exposures, drafts opt-out steps, and **pauses for your explicit approval** before anything is sent externally. It is a tool — not a law firm, investigator, or guaranteed removal service.

### Is Oblivion beta software?

Yes. Oblivion is **beta and experimental**. Features, APIs, connectors, and security controls may change without notice. Use at your own risk. See [Terms](/docs/legal/terms) for the full disclaimer.

### Is this legal or security advice?

No. Nothing in Oblivion or these docs is legal, regulatory, or professional security advice. You are responsible for reviewing each approval before it sends.

### How is my personal information stored?

Raw identifiers (names, emails, URLs, notes) are **encrypted in your browser vault** (AES-256-GCM). The server stores only `encryptedIntake` plus **redacted** case metadata needed to run workflows. We do not sell or profile your data for advertising. See [Privacy](/docs/legal/privacy).

### Does Oblivion guarantee removals?

No. Outcomes depend on third-party sites, brokers, and your specific listings. Oblivion records what was proposed, approved, and executed so you can audit the trail.

---

## Using the app

### How do I start a cleanup?

1. Open [Oblivion](https://oblivion.phantasy.bot)
2. Pick a **template** or describe what to clean up
3. Tap **Start cleanup** — your case opens in the workspace

Or type a one-line request in the landing composer. See [Overview](/docs/user-guide/overview).

### What are templates?

Templates are preset cleanup routes (people-search, breach check, search suppression, etc.). Each drives discovery steps, approvals, and recheck timing. See [Templates](/docs/user-guide/templates).

### What is a case access token?

When you create a case, the app stores a **case access token** in your browser (like a one-time API key for that case only). Consumer `/api/*` routes require this token on every case-scoped request. There is no email/password account — but you still need **both** credentials for full cleanup:

- **Wallet** — billing identity (credits, subscription, per-case activation)
- **Case access token** — capability to read/write that case on `/api/*`

Download a **recovery kit** (Vault tab) to move `caseId` + token to another device. Wallet-linked cases can be listed after connect, but tokens are never re-issued server-side.

### Can anything send without my approval?

**No.** Every disclosure goes through propose → policy check → **your explicit confirmation** → execute. Wallet credits pay for AI and live relay capacity; they do not bypass approvals.

### What does “record-only” mean?

By default, connectors run in **record-only** mode: the agent logs what *would* be sent without making live external calls. Sensitive live connectors require attestation and policy gates. See [Trust & Security](/docs/developers/security).

---

## Credits and wallet

### Do I need a wallet to use Oblivion?

**Free preview:** The landing page can run a limited broker preview (no wallet, no case token) — a few site-scoped checks per day.

**Full cleanup** requires a connected wallet, **per-case activation** (Starter pack or Monitor subscription), and wallet credits for metered steps:

- Full broker discovery (Venice-scored sweep) debits discovery credits per run
- Venice AI chat/classify/draft debits per token use
- Live operator email relay debits per send

Monitor subscribers get monthly credit refills; an active subscription also auto-activates new cases for that wallet without a separate per-case payment.

### What do credits buy?

| Use | Default cost |
|-----|----------------|
| Full broker discovery sweep | 15 credits per run |
| Venice agent chat | 1 credit per 100 tokens (minimum 1) |
| Live operator email relay | 25 credits per send |

**Starter pack:** $5 USDC → 500 credits · **Monitor:** $10 USDC/mo → 1,200 credits/month. Details in [Pricing](/docs/pricing).

### Can I switch between Starter and Monitor later?

Yes — **Settings → Payment rails** for top-ups or subscription.

---

## Compared to other services

### How is Oblivion different from Incogni, DeleteMe, or Optery?

Those services are typically **subscription broker-removal** products with large pre-negotiated broker lists and hands-off operation.

Oblivion is **supervised**: you approve each disclosure, identifiers stay in a **browser vault**, and you can run core workflows **without a subscription**. See the full [pricing comparison](/docs/pricing#how-oblivion-compares).

### When should I use a subscription removal service instead?

If you want fully managed removal, family plans, identity/credit monitoring bundles, or 24/7 phone support — a traditional subscription service may fit better. Oblivion fits when you want **control, transparency, and optional pay-as-you-go** capacity.

---

## Developers and partners

### Consumer API vs Partner API?

- **Consumer API** (`/api/*`) — browser app; case access tokens; for the hosted UI and self-hosted consumer deployments.
- **Partner API** (`/v1/*`) — API keys; embed in password managers, VPNs, security products; separate credit pool.

See [Consumer API](/docs/developers/consumer-api) and [Partner API](/docs/developers/partner-api).

### Can I self-host or embed Oblivion?

Yes. The core is open source. Partners embed via `/v1/*` without server-side vault decrypt. See [Partner onboarding](/docs/developers/partner-onboarding) and [SECURITY.md](https://github.com/thomasjvu/oblivion/blob/main/SECURITY.md).

### Is there an agent skill for Cursor / Claude / Codex?

Yes — install from the [landing page](https://oblivion.phantasy.bot#install-skill) or [SKILL.md on GitHub](https://github.com/thomasjvu/oblivion/blob/main/skills/clean-online-identity/SKILL.md). Same supervised rules as the managed app.

---

## Documentation site

### How do I search the docs?

Press **Cmd/Ctrl + K** to open the command palette, then type your query. Production builds also index full-text search via Pagefind.

### What keyboard shortcuts are available?

| Shortcut | Action |
|----------|--------|
| **Cmd/Ctrl + K** | Command palette |
| **Cmd/Ctrl + I** | Toggle theme |
| **Shift + ← / →** | Previous / next doc page |
| **Esc** | Close dialogs / palette |

### How do I propose doc edits?

Each page footer has **edit**, **issue**, and **source** links to the GitHub repo.

---

## Troubleshooting

| Issue | What to try |
|-------|-------------|
| No dashboard after start | Finish **Start cleanup** — case must be created first |
| Agent blocked | Open **Approvals** — a pending disclosure may need your decision |
| Wrong case | **Cases** sidebar → switch or start new |
| Venice / AI errors | Connect wallet and buy credits in **Settings → Payment rails** |
| Lost case access | Tokens are per-browser — start a new case on a new device |

Still stuck? [Open an issue](https://github.com/thomasjvu/oblivion/issues) on GitHub.

---

[Open Oblivion](https://oblivion.phantasy.bot)

---


## Developers


### Consumer API

URL: /docs/developers/consumer-api

# Consumer API

The Oblivion browser app and self-hosted integrations use `/api/*` with **case access tokens** — no user accounts.

```mermaid
sequenceDiagram
  participant Client
  participant API as Oblivion /api

  Client->>API: POST /api/cases
  API-->>Client: case + accessToken (once)
  Client->>Client: Store token (localStorage or secret store)
  Client->>API: POST /api/cases/:id/intake<br/>Authorization: Bearer token
  Client->>API: POST /api/cases/:id/preset
  Client->>API: POST /api/cases/:id/agent/run
```

---

## Create a case

```sh
curl -sS -X POST http://localhost:8080/api/cases \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction":"US","authorityBasis":"self","riskLevel":"standard"}'
```

Response includes `accessToken` **once**. Store it immediately; the server keeps only `accessTokenHash`.

---

## Authenticated requests

Send the token on every case-scoped route:

```sh
TOKEN="..." # from create response
CASE_ID="case_..."

curl -sS -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/cases/$CASE_ID"

curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"encryptedIntake":{...},"redactedScope":{...}}' \
  "http://localhost:8080/api/cases/$CASE_ID/intake"
```

The Oblivion browser app attaches the header automatically when a token exists for the case id in the path or JSON body.

---

## Public routes (no case token)

- `POST /api/cases` — create
- `POST /api/discovery/preview` — limited broker preview (rate-limited by IP/wallet; no case created)
- `GET /api/presets`, `GET /api/health`, `GET /api/config`
- `GET /api/trust/*`, `GET /api/integrations/*`
- Wallet / x402 catalog endpoints that do not target a specific case

`GET /api/cases` returns `401 case-list-not-available`. The UI keeps case summaries in `localStorage` and refreshes individual cases with tokens.

---

## Wallet case index (no token re-issue)

After a case is activated, link it to the paying wallet for cross-device lookup of **case IDs** (redacted labels only):

```sh
# List cases paid/linked to a wallet (no access tokens returned)
curl -sS "http://localhost:8080/api/wallet/cases?walletAddress=0x..."

# Link case to wallet (requires case Bearer token + wallet address)
curl -sS -X POST http://localhost:8080/api/wallet/cases/link \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"caseId":"case_...","walletAddress":"0x..."}'
```

Users still import `caseId` + `accessToken` from a client-side **recovery kit** — the server never re-issues tokens.

---

## Discovery preview vs full discover

| Route | Auth | Behavior |
|-------|------|----------|
| `POST /api/discovery/preview` | None | Heuristic broker sweep only; daily cap (default 3 previews per IP/wallet per day) |
| `POST /api/cases/:id/findings/discover` | Bearer + activation | Venice-scored discovery; debits discovery credits (default 15) from wallet |

Full discover accepts optional `walletAddress` in the body for subscription auto-activation and credit debit.

---

## Partner cases

Cases created via `/v1/cases` carry `partnerId`. They **cannot** be accessed on `/api/*` (`403 partner-case-use-v1-api`). Use the [Partner API](/docs/developers/partner-api) with your API key.

---

## Security notes

- Treat `caseId` + `accessToken` as a single capability credential.
- Never log tokens or put them in query strings.
- Export and delete require the same token (`assertCaseExportAllowed`).
- Hackathon demo routes (`/api/hackathon/*`) require `HACKATHON_MODE=true` on the server.

Full model: [SECURITY.md](https://github.com/thomasjvu/oblivion/blob/main/SECURITY.md#consumer-api-authentication) in the open-source repo.

---


### Partner API

URL: /docs/developers/partner-api

# Partner API

Embed broker cleanup **without becoming a data custodian**. Raw identifiers stay in the **user's browser vault** (AES-256-GCM). Your servers get `caseId`, redacted labels, exposure URLs, and webhooks.

```mermaid
flowchart TB
  subgraph Partner["Your backend"]
    API[Partner API key]
    WH[Webhook handler]
  end

  subgraph User["User browser"]
    Vault[Vault SDK encrypt]
    UI[Approval panel]
  end

  subgraph Oblivion["Oblivion /v1"]
    Case[Case + template]
    Agent[Discover + run]
    Gate[Policy + approve]
  end

  API --> Case
  Vault --> Case
  Case --> Agent
  Agent --> Gate
  Gate --> UI
  UI --> Gate
  Agent --> WH
```

[Onboarding runbook](/docs/developers/partner-onboarding) · [API reference](/docs/developers/api-reference) · [`openapi-v1.yaml`](/openapi-v1.yaml) · [Open in Swagger Editor](https://editor.swagger.io/?url=https://oblivion-docs.pages.dev/openapi-v1.yaml)

**Consumer vs partner billing:** End users buy **wallet credits** via x402 ([Pricing](/docs/pricing)). Partners use a **separate API-key credit pool** metered per case, discovery, execute, and AI — no user wallet required.

---

## Quick start

Configure partner API keys when you deploy Oblivion ([README](https://github.com/thomasjvu/oblivion/blob/main/README.md)). Use sandbox keys for development.

1. `POST /v1/cases` — jurisdiction, `externalRef`
2. **Browser:** `@oblivion/vault-sdk` → encrypt intake → `POST /v1/cases/:id/intake`
3. `POST /v1/cases/:id/preset` → `/discover` → `/run`
4. Surface approval cards — user types confirmation (≥8 chars). **API key cannot approve.**

Demo: `examples/partner-demo/index.html`

```sh
curl -sS -H "Authorization: Bearer obl_live_..." http://localhost:8080/v1/partners/me
```

---

## Trust boundaries

| Layer | Partner sees | User vault |
|-------|----------------|------------|
| Create | `caseId`, `externalRef` | — |
| Intake | `encryptedIntake` + `redactedScope` | Key never leaves browser |
| Discovery | URLs, scores, redacted snippets | — |
| Approve | Destination, categories, purpose | User confirms |
| Execute | Status, recorded or live | Browser handoff after approve |

`GET /v1/trust/attestation` — no auth required.

**Route isolation:** Partner cases (`partnerId` set) must use `/v1/*` with your API key. Consumer `/api/*` returns `403 partner-case-use-v1-api` even if `caseId` is known. End-user browser sessions use [case access tokens](/docs/developers/consumer-api) on `/api/*` — distinct from partner keys.

---

## Templates (v1)

- `people-search-cleanup` — broker discovery + opt-out
- `breach-exposure` — breach email check + password range (prefix-only)

Live broker submission needs production trust verification and user approval.

---

## Widgets (`@oblivion/partner-ui`)

| Widget | Purpose |
|--------|---------|
| `OblivionApprovalPanel` | Disclosure cards + user confirmation |
| `OblivionStatusPanel` | Phase, pending approvals, recheck |
| `OblivionStatusBadge` | Trust / runtime indicator |

**Sandbox:** use sandbox-issued keys; `GET /v1/partners/me` returns `environment: "sandbox"`.

**Rotate:** `POST /v1/partners/me/rotate-key` — new key returned once.

---

## Core endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/v1/cases` | Create (idempotent on `externalRef`) |
| `POST` | `/v1/cases/:id/intake` | Encrypted intake (browser) |
| `POST` | `/v1/cases/:id/preset` | Start template |
| `POST` | `/v1/cases/:id/discover` | Exposure discovery |
| `POST` | `/v1/cases/:id/run` | One agent step |
| `POST` | `/v1/cases/:id/run-until-blocked` | Until approval/blocked/complete |
| `POST` | `/v1/approvals/:id/approve` | User confirmation required |
| `POST` | `/v1/actions/:id/execute` | After approve |
| `POST` | `/v1/webhooks` | Register webhook |
| `POST` | `/v1/webhooks/register-inbox` | Dev inbox (no external server) |
| `GET` | `/v1/cases/:id/status` | Phase + pending |
| `GET` | `/v1/cases/:id/export` | Redacted export (audited) |
| `DELETE` | `/v1/cases/:id` | Purge case |
| `GET` | `/v1/partners/me/usage` | Metering |
| `POST` | `/v1/billing/invoices/close` | Close period invoice |

Full request/response shapes: [OpenAPI v1](/openapi-v1.yaml)

---

## Webhooks

HMAC-SHA256: `X-Oblivion-Signature` over `{timestamp}.{body}`.

Events: `case.created` · `exposure.discovered` · `approval.pending` · `approval.approved` · `action.executed` · `recheck.due` · `case.completed` · `case.deleted`

Retries: `GET /v1/webhooks/deliveries?status=failed` · `POST .../retry`

---

## Never do

- Decrypt `encryptedIntake` server-side
- Approve with partner API key only
- Auto-approve or bypass gates
- Send raw PII to your LLM or analytics

```sh
npm install @oblivion/partner-sdk @oblivion/vault-sdk
```

[Open Oblivion](https://oblivion.phantasy.bot)

---


### Partner Onboarding

URL: /docs/developers/partner-onboarding

# Partner Onboarding

30-minute path to a working people-search integration.

```mermaid
flowchart TB
  A[1. Credentials] --> B[2. Webhooks]
  B --> C[3. SDK + vault]
  C --> D[4. Demo checklist]
```

**Prerequisites:** Oblivion API (local or hosted) · HTTPS webhook URL (or dev inbox) · browser page for vault + approvals

---

## 1. Credentials (5 min)

Issue partner API keys when you deploy Oblivion ([README](https://github.com/thomasjvu/oblivion/blob/main/README.md)). Use sandbox keys for local development.

```sh
curl -s http://localhost:8080/v1/partners/me -H "Authorization: Bearer obl_live_..."
```

## 2. Webhooks (5 min)

**Local:** `POST /v1/webhooks/register-inbox` — deliveries at `GET /v1/partners/me/webhook-inbox`

**Production:** `POST /v1/webhooks` with `url` + `secret` — verify with `@oblivion/partner-sdk/webhooks`

Events: `case.created` · `exposure.discovered` · `approval.pending` · `approval.approved` · `action.executed` · `recheck.due` · `case.completed`

## 3. SDK (10 min)

```html
<script type="module">
  import { OblivionPartnerClient } from "/packages/partner-sdk/index.js";
  import { OblivionApprovalPanel } from "/packages/partner-ui/widgets.js";
  import { createVaultKey, encryptVaultPayload, buildEncryptedIntake } from "/packages/vault-sdk/...";

  const client = new OblivionPartnerClient({ baseUrl: "...", apiKey: "..." });
  const { case: c } = await client.createCase({ jurisdiction: "US", authorityBasis: "self", externalRef: "user_12345" });

  const vaultKey = await createVaultKey();
  const intake = await buildEncryptedIntake(vaultKey, c.id, { contactEmail: "..." }, encryptVaultPayload);
  await client.submitIntake(c.id, intake);

  await client.applyPreset(c.id, "people-search-cleanup");
  await client.runUntilBlocked(c.id);

  new OblivionApprovalPanel({ client, caseId: c.id, container: "#approvals" }).refresh();
</script>
```

Reference: [/examples/partner-demo/index.html](/examples/partner-demo/index.html)

## 4. Demo checklist (10 min)

| Step | API | You see |
|------|-----|---------|
| Create | `POST /v1/cases` | `caseId`, `externalRef` |
| Intake | `POST .../intake` | ciphertext + redacted labels |
| Preset | `POST .../preset` | `case.phase_changed` webhook |
| Discover | `POST .../discover` | exposure URLs |
| Confirm | `POST .../exposures/:id/confirm` | — |
| Run | `POST .../run-until-blocked` | `approval.pending` |
| Approve | `POST /v1/approvals/:id/approve` | `approval.approved` |
| Execute | `POST /v1/actions/:id/execute` | `action.executed` |

---

## Security checklist

- [ ] Vault key never on partner backend
- [ ] API key in secrets manager, not client bundle
- [ ] User types approval confirmation
- [ ] Webhook signatures verified
- [ ] `GET /v1/trust/runtime` matches expected mode

**Rotate:** `POST /v1/partners/me/rotate-key` · **Invoice:** `POST /v1/billing/invoices/close` with `{"period":"2026-06"}`

[Partner API](/docs/developers/partner-api) · [Open Oblivion](https://oblivion.phantasy.bot)

---


### API Reference

URL: /docs/developers/api-reference

---
title: API Reference
description: OpenAPI specifications for Oblivion consumer and partner integrations.
---

# API Reference

Machine-readable OpenAPI specs live outside the docs reader so guides stay uncluttered. Use the links below to download YAML or open an external explorer in a new tab.

> **Beta software** — Oblivion is experimental. API shapes may change; integrate at your own risk.

## Resources

- [Consumer API](/docs/developers/consumer-api) — case access tokens, `/api/*` auth
- [Partner API guide](/docs/developers/partner-api) — auth, cases, webhooks, billing
- [Partner onboarding](/docs/developers/partner-onboarding) — 30-minute design-partner checklist

## Download specs

| Spec | YAML |
|------|------|
| Partner API (`/v1/*`) | [`openapi-v1.yaml`](/openapi-v1.yaml) |
| Consumer API (`/api/*`) | [`openapi-consumer.yaml`](/openapi-consumer.yaml) |

On this docs site, specs are served at `/openapi-v1.yaml` and `/openapi-consumer.yaml`. The Oblivion API server also mirrors partner YAML at `/docs/openapi-v1.yaml` when you run the app locally.

## Open in external explorer

These open **Swagger Editor** in a new tab with the hosted spec URL:

- [Partner API — open in Swagger Editor](https://editor.swagger.io/?url=https://oblivion-docs.pages.dev/openapi-v1.yaml)
- [Consumer API — open in Swagger Editor](https://editor.swagger.io/?url=https://oblivion-docs.pages.dev/openapi-consumer.yaml)

## Base URLs

**Consumer** routes use `/api/*` on your deployment (browser app default).

**Partner** routes use `/v1/*` with a partner API key:

```sh
curl -sS -H "Authorization: Bearer obl_live_..." \
  http://localhost:8080/v1/partners/me
```

---


### Hackathon Demo

URL: /docs/developers/hackathon-demo

# Hackathon Demo

**3-minute judge walkthrough** for private identity cleanup: encrypted intake, explicit approvals, and crypto-native payment rails. Every integration demo runs behind the same safety gates — no checklist bypass.

```mermaid
flowchart TB
  subgraph UI["Oblivion app"]
    Start[Start case] --> Vault[Browser vault] --> Agent[Agent panel]
    Agent --> Approvals[Approval cards]
    Settings[Settings]
    Trust[Trust tab]
  end

  subgraph Gates["Safety gates"]
    Encrypt[Encrypt intake]
    Policy[Policy check]
    Confirm[Your confirmation]
    Redact[Redact logs and prompts]
  end

  subgraph Integrations["Hackathon tracks"]
    Wallet[MetaMask Smart Account]
    Pay[x402 credits]
    Venice[Venice AI]
    Agents[Sub-agent delegation]
    Relay[1Shot relayer]
  end

  Encrypt --> Agent
  Agent --> Policy --> Approvals --> Confirm
  Redact --> Venice
  Settings --> Wallet
  Settings --> Pay --> Venice
  Settings --> Agents
  Settings --> Relay
  Trust --> Policy
```

Checklist status: **Settings → Developer details** or `GET /api/hackathon/status?caseId=...` (requires `HACKATHON_MODE=true` on the server — off by default in production)

---

## 3-minute script

| Time | Show |
|------|------|
| 0:00–0:30 | Problem + encrypted vault intake |
| 0:30–1:00 | Connect MetaMask Smart Account |
| 1:00–1:20 | Finish pending tracks (developer checklist) |
| 1:20–1:45 | Buy credits via x402 (if configured) |
| 1:45–2:05 | Approval gate — read disclosure, confirm |
| 2:05–2:25 | Execute (practice run or live) |
| 2:25–2:45 | Venice AI + sub-agent delegation |
| 2:45–2:55 | 1Shot relay (if live) |
| 2:55–3:00 | Trust tab — attestation and safety invariants |

---

## Judge flow

```mermaid
sequenceDiagram
  participant Judge
  participant UI as Oblivion UI
  participant API as Oblivion API
  participant MM as MetaMask
  participant X402 as x402 facilitator
  participant Venice as Venice.ai
  participant Shot as 1Shot relayer

  Judge->>UI: Create case and vault intake
  Judge->>UI: Connect wallet
  UI->>MM: Smart Account calls (if live)
  UI->>API: Register demo session
  Judge->>UI: Finish pending tracks
  UI->>API: Complete pending integrations
  API->>Venice: Classify case (redacted)
  Judge->>UI: Buy credits (if configured)
  UI->>X402: USDC payment signature
  API->>API: Credit wallet balance
  Judge->>UI: Approve then execute
  opt Live 1Shot
    UI->>API: Relay payment
    API->>Shot: JSON-RPC
  end
  Judge->>API: Fetch hackathon status
```

---

## Track matrix

| Track | Where to start | Demo mode | Live mode |
|-------|----------------|-----------|-----------|
| **Best Agent** | Presets + agent panel | Always works | Practice-run execution |
| **MetaMask** | Connect wallet | Demo grants shown | Smart Account live calls |
| **x402 credits** | Settings → Payment rails | Authorized session | Real USDC settlement |
| **ERC-7710** | Payment rails permission | Demo delegation | Scoped live permission |
| **Venice AI** | Agent chat / classify | Blocked without API key | Needs credits + key |
| **A2A delegation** | Settings → delegate | In-memory scoped grants | Same API path |
| **1Shot relay** | Settings → relay | Finish-pending events | Live JSON-RPC relay |

---

## What to say about safety

- **Demo data only** — use synthetic identity; never real SSNs or passwords in prompts or logs
- **Local dev trust** — attestation shows not-configured until production trust center; sensitive live connectors are blocked by design
- **Delegation** — scoped in-app grants for the demo, not a full external agent wire protocol
- **Credits** — Starter pack (500 credits) and Monitor (1,200/month) fund Venice; approvals still required for every send

---

## Live tracks (operators)

If you are hosting the demo with live integrations, configure API keys and payment rails per the repo [README](https://github.com/thomasjvu/oblivion/blob/main/README.md). Set `HACKATHON_MODE=true` on the API host to expose `/api/hackathon/*`. Poll `GET /api/integrations/status` and `GET /api/hackathon/status?caseId=...` (with case access token) to verify readiness.

[Open Oblivion](https://oblivion.phantasy.bot)

---


### Trust & Security

URL: /docs/developers/security

# Trust & Security

Oblivion minimizes trust surface area. Third-party services (brokers, search engines, breach checkers) may receive identifiers **only after you approve** a specific action.

```mermaid
flowchart TB
  subgraph Browser["Your browser"]
    Vault[Encrypted vault]
    Confirm[Your confirmation]
    Wallet[Wallet address]
  end

  subgraph Server["Oblivion server"]
    Cipher[Encrypted intake only]
    Policy[Policy check]
    Redact[Redaction layer]
    Credits[Credit ledger]
    Record[Practice-run default]
  end

  subgraph TEE["Trusted environment (production)"]
    Quote[Hardware attestation]
    Plain[Managed plaintext window]
  end

  Vault --> Cipher --> Policy
  Wallet --> Credits
  Policy --> Confirm --> Record
  Credits --> Record
  Redact --> Record
  Quote --> Plain --> Record
```

---

## How Oblivion protects you

| Control | What it does |
|---------|----------------|
| Browser vault | Raw identifiers encrypted before anything is stored server-side |
| Server storage | Ciphertext plus minimal redacted metadata — not readable without your key |
| Policy | Blocks disallowed actions before AI or external tools run |
| Approval gates | Every sensitive send requires your explicit confirmation |
| Trust center | Hardware attestation before live sensitive connectors in production |
| Practice-run default | Live external sends stay behind approval and trust checks |
| Wallet credits | AI and email relay are metered; ledger entries contain no PII |

---

## Approval boundary

Every sensitive action binds: destination · action type · identifier categories · data disclosed · purpose · risk · expiry · **your confirmation**. Broad or vague consent is rejected.

---

## API authentication

| Surface | Credential | Notes |
|---------|------------|-------|
| Consumer `/api/*` | Case access token | Returned once at `POST /api/cases`; `Authorization: Bearer` on all other case routes |
| Partner `/v1/*` | Partner API key | Partner cases cannot use consumer `/api/*` |
| Trust | None | `GET /api/trust/attestation`, `GET /v1/trust/attestation` |

The browser stores tokens in `localStorage` (`oblivion.caseTokens`). There is no open case listing endpoint — the app keeps local summaries and fetches cases individually.

Details: [Consumer API](/docs/developers/consumer-api) · [Partner API](/docs/developers/partner-api)

---

## Never store in Oblivion

Passwords · full SSNs · government IDs · payment cards · recovery codes · unredacted identity documents

---

## Portable agent skill

The repo includes an installable cleanup workflow skill for other AI agents. Using it does **not** guarantee the host agent, logs, or model provider are private — review their policies separately.

---

## Self-hosting & production

Deploying Oblivion yourself? Production checklists, secrets, attestation, and executor modes are documented in the open-source repo:

- [SECURITY.md](https://github.com/thomasjvu/oblivion/blob/main/SECURITY.md) — production requirements and trust model
- [README.md](https://github.com/thomasjvu/oblivion/blob/main/README.md) — setup and configuration

Partners can verify deployment trust without authentication: `GET /v1/trust/attestation`

---


### LLMs.txt

URL: /docs/llms

# LLMs.txt

Oblivion publishes machine-readable documentation exports for AI tools, agents, and internal automation.

## Generated files

- `/llms.txt` — summary index with canonical doc links
- `/llms-full.txt` — full text corpus for retrieval workflows

## Why they exist

These files give AI systems a stable text entry point without crawling the interactive docs UI.

## Updates

Exports refresh automatically when the docs site is rebuilt. Published pages in the docs tree are included in both files.

## Helpful links

<a href="/llms.txt" class="download-link" data-file="llms.txt">Download llms.txt</a>

<a href="/llms-full.txt" class="download-link" data-file="llms-full.txt">Download llms-full.txt</a>

<a href="#" class="copy-link" data-url="/llms.txt">Copy llms.txt URL</a>

## Preview

{llms-preview}

---


## Legal


### Privacy

URL: /docs/legal/privacy

<div class="legal-page-header">

# Privacy Policy

<p class="legal-last-updated"><strong>Last updated:</strong> June 9, 2026</p>

</div>

Oblivion is built so you can clean up your online footprint without handing your identity to us. This policy explains what we do — and deliberately do not do — with information when you use the Oblivion web app and related open-source materials.

## Beta software

Oblivion is **beta / experimental** software. We make no warranty that data handling, removal outcomes, or security controls will meet your expectations. Use at your own risk.

## Our core rule

**We do not collect, sell, or profile your personal data for advertising.** Sensitive identifiers stay in your browser vault. The server stores only encrypted intake blobs and redacted case metadata needed to run supervised cleanup workflows.

## What stays on your device

- Raw identifiers you enter (names, emails, URLs, notes) are encrypted in the browser before intake is sent.
- Vault keys live in browser memory during a session; they are not written to our servers in plaintext.
- **Case access tokens** returned when you create a case are stored in browser `localStorage` (`oblivion.caseTokens`) so the app can authenticate API requests. Treat your browser like a password manager — anyone with access to this device may access active cases.
- **Device-local state** may also include: active case id, redacted case summaries, pasted discovery URL lists, UI preferences (sidebar, privacy filter, payment mode), and agent skill install metadata. Discovery URL lists may contain sensitive links you pasted for review.
- When you delete a case in the app, server-side case data is purged. Local browser storage for that case (tokens, summaries, discovery lists) should be cleared by the client; you can also clear site data in your browser settings.

## What the server may store

When you create a case, the server keeps:

- **Encrypted intake** (AES-256-GCM ciphertext your browser produced — we cannot read it without your key)
- **Redacted metadata** (jurisdiction, risk level, authority basis, redacted scope labels — no raw PII)
- **Access token hash** (one-way hash of your case access token — not the token itself)
- **Workflow records** (approvals, timeline events, connector results, and execution logs — redacted)
- **Wallet address** (if you connect a wallet for credits or Venice AI metering — used for a server-side credit ledger, not for marketing profiles)
- **Retention** — cases default to a 90-day retention window unless you delete sooner

Partner API integrations (B2B) use separate API-key auth; partner cases do not use consumer case access tokens on `/api/*`.

When you delete a case, associated server-side records (intake, approvals, timeline, and related workflow data) are removed.

## What we do not do

- No advertising or behavioral tracking
- No analytics pixels or third-party marketing SDKs in the app
- No account signup database of personal profiles
- No sale or rental of user information
- No training AI models on your plaintext identifiers

## Third-party services

If you choose to connect a wallet, use MetaMask, or enable optional integrations (for example Venice AI, x402 payments, 1Shot relayer demos, or Phala attestation in production), those providers operate under their own policies. Oblivion only sends **redacted** inputs across approval boundaries unless you explicitly approve a sensitive disclosure action.

Hosted deployments may use Cloudflare (UI/static assets) and Phala (TEE API runtime in production). Self-hosted copies follow your infrastructure policies.

## Logs

Server logs use redaction helpers so plaintext identifiers, secrets, and encrypted payload bodies should not appear in operational logs. Do not paste secrets into free-text fields that bypass the vault.

## Children

Oblivion is not directed at children under 13. We do not knowingly collect personal information from children.

## Changes

We may update this policy as the product evolves. Material changes will be reflected in this document with an updated date.

## Contact

Questions about privacy: open an issue at [github.com/thomasjvu/oblivion](https://github.com/thomasjvu/oblivion) or contact the maintainer listed in the repository.

---


### Terms

URL: /docs/legal/terms

<div class="legal-page-header">

# Terms of Service

<p class="legal-last-updated"><strong>Last updated:</strong> June 9, 2026</p>

</div>

These terms govern your use of the Oblivion web application and related open-source materials. By using Oblivion, you agree to these terms.

## Beta / experimental software

Oblivion is **beta and experimental**. Features, APIs, connectors, and security controls may change or fail without notice. **You use Oblivion at your own risk.** We do not guarantee removal outcomes, uptime, data deletion by third parties, or freedom from security vulnerabilities.

## What Oblivion is

Oblivion is a **supervised cleanup agent** that helps you discover exposure listings, draft opt-out requests, and pause for your approval before anything is sent externally. It is a tool, not a law firm, investigator, or guaranteed removal service. **Nothing here is legal or security advice.**

## No data harvesting

Oblivion is designed **not** to collect your personal data for marketing or resale. You control what enters the encrypted vault. We do not operate a traditional user account database of identity records.

## Your responsibilities

You agree that you will:

- Only submit information you are authorized to manage
- Review and approve disclosures before they leave the approval boundary
- Use accurate jurisdiction and authority basis selections when starting a case
- Comply with applicable law when requesting data removal or suppression
- Protect case access tokens stored on your device (see [Privacy Policy](/docs/legal/privacy))

You are responsible for decisions you approve in the app.

## Case access tokens

Consumer cases use browser-stored access tokens to call `/api/*`. **You are responsible for device security.** Anyone with access to your browser profile or `localStorage` may be able to act on your cases until you delete them or clear site data.

## No warranty

Oblivion is provided **"as is"** without warranties of any kind, express or implied, including merchantability, fitness for a particular purpose, or non-infringement. We do not guarantee that brokers, search engines, or other parties will honor removal requests, respond within a timeframe, or delete all copies of data.

## Limitation of liability

To the fullest extent permitted by law, Oblivion contributors and operators are not liable for indirect, incidental, special, or consequential damages arising from your use of the service, including missed deadlines, rejected requests, continued publication of information by third parties, loss of tokens, or unauthorized use of an unlocked browser session.

## Approvals and automation

Automated steps run only within policy gates. Sensitive connectors and external submissions require explicit approval. You may revoke wallet access or delete cases at any time.

## Open source and self-hosting

Source code is available under the repository license. You may inspect, self-host, or modify the software subject to that license. **Self-hosted deployments are your responsibility** — including secrets, backups, TLS, and compliance.

## Changes

We may update these terms. Continued use after the "Last updated" date means you accept the revised terms.

## Governing approach

These terms are written in plain language to match the product's privacy-first design. If you need legal advice about your specific situation, consult a qualified professional.

## Contact

Questions about these terms: open an issue at [github.com/thomasjvu/oblivion](https://github.com/thomasjvu/oblivion).

---