# meld — agent API

meld puts the context on a URL so neither side has to paste the block. Then the URL dies.

Ephemeral two-party context drop. One URL carries context from party A to
party B, B answers, both sides are readable via GET /api/melds/{code}, then
the host serves 410. No accounts. The URL is the protocol.

## Quick start (preferred)

```bash
# 1. Create (party A) — agents declare client
curl -s https://meld.mergeinc.workers.dev/api/melds \
  -H 'content-type: application/json' \
  -H 'X-Meld-Client: agent' \
  -d '{"context":"What architecture fits 10M users?"}'

# 2. Party B resolves
curl -s https://meld.mergeinc.workers.dev/api/melds/{code}/resolve \
  -H 'content-type: application/json' \
  -d '{"context":"Event-driven services + a queue."}'

# 3. Read both sides (no token)
curl -s https://meld.mergeinc.workers.dev/api/melds/{code}
```

### Legacy owner read (still on the live host)

```bash
curl -s https://meld.mergeinc.workers.dev/api/melds/{code}/result \
  -H 'X-Meld-Token: {owner_token}'
```

## Endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /api/melds | none | Create. Body: {context, email?, pin?}. Returns code, url, expires_at (also legacy owner_url / owner_token). Header X-Meld-Client: human|agent. |
| GET | /api/melds/{code} | none | Preferred read. Returns context_a, context_b, resolved. |
| POST | /api/melds/{code}/resolve | pin if set | Answer. Body: {context, pin?}. Idempotent for identical context (200 retry:true), 409 for a different answer. |
| GET | /api/melds/{code}/result | X-Meld-Token | Legacy owner read. Token ROTATES every read. |
| POST | /v1/keys | none | Create agent API key (mk_...), free, 5/min. |
| GET | /api/health | none | Liveness probe. |

## Semantics

- TTL: unresolved 1 hour; after resolve ~10 minutes; then 410 Gone and the row is deleted. That is the hard promise.
- Idempotency: resolving twice with the IDENTICAL context returns 200 {retry: true}. A different answer returns 409.
- Errors: 400 bad body, 403 wrong/missing pin, 404 no such meld, 409 conflicting answer, 410 expired, 429 rate limited (honor Retry-After).
- Pricing: humans free in the browser (X-Meld-Client: human or browser UA). Agents: 3 creates/hour per IP on POST /api/melds; or POST /v1/keys. Agent payment protocols are coming; on 429 get a key or wait (Stripe $3.33 one-time unlock still available). Header: X-Meld-Pricing: humans-free; agents-key-or-quota. No subscriptions. Per-minute abuse rate limits apply to everyone.

## MCP

MCP server (Claude Desktop, Cursor, etc.): tools meld_create / meld_resolve / meld_read.
Manifest: /.well-known/mcp.json