# Verbaterm Agent Skill

> Judged, citation-checked policy intelligence for agents. Every finding
> ships with verbatim source excerpts and provenance, so you can show
> receipts instead of re-deriving the fine print.

Informational only. Not legal advice. Raw third-party policy text is never
served — all payloads are Verbaterm-derived, judged data.

## Base URLs

- Production: https://verbaterm.com
- REST root: https://verbaterm.com/api
- OpenAPI 3.1: https://verbaterm.com/openapi.json
- MCP endpoint (streamable HTTP, JSON): https://verbaterm.com/mcp
- MCP server.json: https://verbaterm.com/mcp/server.json
- MCP well-known: https://verbaterm.com/.well-known/mcp
- Discovery doc: GET https://verbaterm.com/api/v1

## Access model (two meters)

1. **Public corpus reads** — free keyless at 150 requests/day per IP
   (1–2 QPS), then API credits. 1 credit = 1 successful
   derived read. Failed auth/validation never debits.
2. **AI actions** — private review starts and Ask/Q&A require a Verbaterm
   API key (`Authorization: Bearer <key>`) and debit the caller's own plan
   allowance (Free/Pro/Business), never API credits. The same meters power
   the web app — agents are never double-charged.

Get an API key: sign up at https://verbaterm.com/sign-up then open
https://verbaterm.com/account#developer-api-keys to mint a Clerk API key.
Pricing (Hobby $19 / 5k credits): https://verbaterm.com/developers?credits=5000

## REST endpoints

### Public corpus (keyless)

```bash
# List every published review in the corpus
curl https://verbaterm.com/api/library

# Search by company/product
curl "https://verbaterm.com/api/library/search?q=netflix&limit=10"

# Full judged review (findings, citations, scores, provenance)
curl https://verbaterm.com/api/library/reviews/{companySlug}/{productSlug}/{policyKind}
```

`policyKind` is one of `terms`, `privacy`, `cookies`, `data_processing`, `other`.

### AI actions (API key required)

```bash
# Start a private review of pasted text (debits plan allowance)
curl -X POST https://verbaterm.com/api/v1/reviews \
  -H "Authorization: Bearer $VERBATERM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"policyText": "<full policy text, min 80 chars>", "policyKind": "terms"}'
# → 202 { "sessionId": "review-…", "progressUrl": "…", "resultUrl": "…" }

# Poll progress until status = complete
curl https://verbaterm.com/api/v1/reviews/{sessionId}/progress \
  -H "Authorization: Bearer $VERBATERM_API_KEY"

# Fetch the judged result (source text is not echoed back)
curl https://verbaterm.com/api/v1/reviews/{sessionId} \
  -H "Authorization: Bearer $VERBATERM_API_KEY"

# Ask a citation-grounded follow-up on a public review or private session
curl -X POST https://verbaterm.com/api/v1/ask \
  -H "Authorization: Bearer $VERBATERM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewRef": {"kind": "public_path", "companySlug": "webull", "productSlug": "webull", "policyKind": "terms"}, "question": "Does this allow third-party data sharing?"}'
```

## MCP tools (POST https://verbaterm.com/mcp)

Public tools (keyless): `search_policies`, `list_policies`, `get_policy_review`.
Authed tools (Bearer key): `start_private_review`, `get_private_review_progress`,
`get_private_review_result`, `ask_question`.

Client config example:

```json
{
  "mcpServers": {
    "verbaterm": {
      "url": "https://verbaterm.com/mcp",
      "headers": { "Authorization": "Bearer $VERBATERM_API_KEY" }
    }
  }
}
```

## Errors are agent-legible JSON

- `401 unauthorized` — keyless route used a key-only endpoint (or bad key).
- `402 allowance_exhausted` — plan meter is empty; body links https://verbaterm.com/plans.
- `404 not_found` — no published review at that path; search first.
- `413 document_too_long` — plan document ceiling; Pro raises it.
- `429 rate_limited` — keyless IP daily cap hit; body includes
  `account` (https://verbaterm.com/account#developer-api-keys) and
  `upgrade` (Hobby $19 / 5k at https://verbaterm.com/developers?credits=5000).
- `429 credits_exhausted` — authenticated monthly API credits used up;
  body includes the same `upgrade` URL (not the keyless rate-limit case).

## Recommended workflows

**Answer "what does X's policy say?"** — `search_policies` →
`get_policy_review` → quote findings with their citation excerpts and link
the `url` field. Do not invent clauses that are not in the payload.

**Review a user's pasted document** — `start_private_review` → poll
`get_private_review_progress` → `get_private_review_result` →
summarize top findings, then offer `ask_question` follow-ups.

## Rules

1. Always show citations back to the user — that is the product.
2. Never claim this is legal advice.
3. Cache public reads within your task; credits are per successful read.