# govlaws.ai

U.S. federal regulation data for AI agents. Instant citation lookup, semantic search, change detection, and a programmable control plane over official government sources (eCFR + Federal Register).

## What this is

govlaws.ai is a REST API that gives AI agents structured access to U.S. federal regulations. Instead of scraping .gov websites, agents call our API to get current regulatory text with provenance metadata anchored to official government sources. The current V1 surface adds usage tracking, budget controls, webhook subscriptions, and key rotation for agent-managed accounts.

## Quick start (3 calls)

### 1. Start signup (returns Stripe checkout URL)
```
curl -X POST https://www.govlaws.ai/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "your-agent@yourcompany.ai", "plan": "free"}'
```
Response includes a `checkout_url`. Complete checkout (free tier collects a payment method but does not charge). Then poll `GET /api/signup/status?session_id={session_id}` to retrieve your API key.

### 2. Resolve a citation
```
curl "https://www.govlaws.ai/api/resolve?citation=12+CFR+1026.43" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 3. Search regulations
```
curl -X POST https://www.govlaws.ai/api/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mortgage underwriting qualified mortgage standards", "limit": 5}'
```

## Authentication

All endpoints (except /api/signup and /api/status) require:
- Header: `Authorization: Bearer glaw_sk_live_...`
- Or: `X-API-Key: glaw_sk_live_...`

## MCP server

GovLaws also exposes a read-only remote MCP server for agent installs:
- Endpoint: `https://www.govlaws.ai/mcp`
- Auth: `Authorization: Bearer glaw_sk_live_...`
- Tools: `resolve`, `search`, `changes`

Use MCP when your agent client supports direct remote tool installation. Use the REST API when you are building a direct integration, and use MPP when you want no-account pay-per-request access.

## Core Endpoints

### POST /api/signup
Create account via Stripe checkout. No form, no approval queue.
- Body: `{"email": "...", "plan": "free|developer|pro"}`
- Returns: checkout_url, session_id, plan, requests_limit
- After checkout: `GET /api/signup/status?session_id={id}` returns api_key (shown once)

### GET /api/resolve?citation={citation}
Resolve a CFR citation to current text + provenance.
- Example: `?citation=12+CFR+1026.43`
- Returns: title, text, source URL, freshness timestamp, recent changes, provenance object

### POST /api/search
Semantic search over federal regulations.
- Body: `{"query": "...", "limit": 5}`
- Returns: ranked results with citation, title, relevance score, snippet

### GET /api/changes
Recent regulatory changes from the Federal Register.
- Params: `?agency=CFPB&days=30` or `?citation=12+CFR+1026`
- Returns: list of change events with effective_date, document_number, FR URL

### GET /api/status
System health and data freshness (no auth required).
- Returns: healthy/degraded status, last_sync timestamps per source

## V1 Endpoints

### GET /api/usage
Current plan, request counts, billing period, and budget status.
- Returns: plan, requests_used, requests_limit, period, budget (if configured)
```
curl https://www.govlaws.ai/api/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### GET /api/budgets
Retrieve current budget configuration.
- Returns: budget object with caps, current spend, status

### POST /api/budgets
Set or update spend controls. Requires Pro plan. Writes an audit event on every change.
- Body: `{"soft_cap_usd": 150, "hard_cap_usd": 200, "notify_webhook_url": "https://your-agent.ai/webhooks/budget"}`
- Returns: budget object with updated values
```
curl -X POST https://www.govlaws.ai/api/budgets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"soft_cap_usd": 150, "hard_cap_usd": 200}'
```

### GET /api/subscribe
List your active webhook subscriptions. Requires Pro plan.
- Returns: array of subscriptions with id, citation_pattern, webhook_url, status

### POST /api/subscribe
Register a webhook to receive change notifications. Requires Pro plan. Max 50 active subscriptions.
- Body: `{"citation_pattern": "12 CFR 1026.*", "webhook_url": "https://...", "webhook_secret": "whsec_...", "filters": {"change_types": ["amendment", "final_rule"]}}`
- Returns: subscription_id, status
- Payloads are signed with HMAC-SHA256 via `X-Govlaws-Signature` header
- Retries with exponential backoff: 1m, 5m, 30m, 2h, 24h
```
curl -X POST https://www.govlaws.ai/api/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"citation_pattern": "12 CFR 1026.*", "webhook_url": "https://your-agent.ai/webhooks/govlaws", "webhook_secret": "whsec_your_secret_here"}'
```

### DELETE /api/subscribe?id={subscription_id}
Deactivate a webhook subscription.
- Returns: subscription_id, status: "deactivated"

### POST /api/keys/rotate
Rotate a key: deactivates the old key and issues a new one with the same name.
- Body: `{"id": "key_id_to_rotate"}`
- Returns: new plaintext api_key (shown ONCE), old key info

## Rate limits

| Plan      | Price         | Requests/month |
|-----------|---------------|----------------|
| free      | $0            | 10             |
| developer | $49/mo        | 5,000          |
| pro       | $499/mo       | 100,000        |

Rate limit headers returned on every response:
- `X-RateLimit-Limit` — monthly limit
- `X-RateLimit-Remaining` — requests left this month
- `X-RateLimit-Reset` — ISO 8601 timestamp when limit resets

429 responses include `upgrade_url` and `reset_at` fields.

## Plan-gated features

| Feature        | Free | Developer | Pro |
|----------------|------|-----------|-----|
| resolve        | ✓    | ✓         | ✓   |
| search         | ✓    | ✓         | ✓   |
| changes        | ✓    | ✓         | ✓   |
| budget controls|      |           | ✓   |
| webhooks       |      |           | ✓   |
| key rotation   |      |           | ✓   |

## Data sources

- **eCFR** (ecfr.gov) — current federal regulations, updated every 4 hours
- **Federal Register** (federalregister.gov) — regulatory changes and notices, updated every 4 hours
- **GovInfo** (govinfo.gov) — official artifact URLs for provenance anchoring

Note: eCFR is not an official legal edition of the CFR. All responses include provenance metadata. Official GovInfo artifact URLs are included when available (null otherwise).

## Provenance

Every `/api/resolve` response includes a `provenance` object:
```json
{
  "provenance": {
    "is_official_edition": false,
    "disclaimer": "Derived from the eCFR, which is not an official legal edition of the CFR.",
    "official_artifact_url": null,
    "govinfo_source_url": "https://www.govinfo.gov/bulkdata/ECFR/title-12/ECFR-title12.xml",
    "ecfr_url": "https://www.ecfr.gov/current/title-12/section-1026.43"
  }
}
```

## Pay-per-request via MPP (no signup required)

GovLaws supports the Machine Payments Protocol (MPP) for agent-native access. No API key, no account, no checkout — just pay per request via Tempo stablecoin.

MPP docs: https://www.govlaws.ai/mpp

### How it works

1. Request a paid endpoint without credentials
2. Receive a `402 Payment Required` response with a Tempo payment challenge
3. Pay the challenge (your MPP client handles this automatically)
4. Retry with payment proof — receive data + payment receipt

### MPP endpoints

#### Resolve a citation ($0.05)
```
GET https://www.govlaws.ai/api/mpp/resolve?citation=12+CFR+1026.43
```

#### Search regulations ($0.03)
```
POST https://www.govlaws.ai/api/mpp/search
Content-Type: application/json
{"query": "mortgage underwriting qualified mortgage standards", "limit": 5}
```

#### Recent changes ($0.03)
```
GET https://www.govlaws.ai/api/mpp/changes?agency=CFPB&days=30
```

### Quick test with mppx CLI
```bash
npx mppx account create
npx mppx https://www.govlaws.ai/api/mpp/resolve?citation=12+CFR+1026.43
```

### Agent prompts

- "Resolve 12 CFR 1026.43 using GovLaws via MPP"
- "Search current CFPB mortgage servicing regulations using GovLaws"
- "Check recent changes to 12 CFR 1026 using GovLaws"

MPP responses include the same provenance, freshness, and source metadata as the API-key endpoints. Payment method: Tempo (pathUSD stablecoin).

## Licensing

API outputs (text, metadata) may be redistributed. The underlying legal text is U.S. federal government work (public domain under 17 U.S.C. § 105).

## Machine-readable spec

Machine-readable docs:
- Remote MCP endpoint: https://www.govlaws.ai/mcp
- OpenAPI 3.1 spec: https://www.govlaws.ai/api/openapi.json
- Full LLM guide: https://www.govlaws.ai/llms-full.txt