# push-live · Docs

Auto-generated from the OpenAPI spec. Compact agent context lives at /llms.txt and /llms-full.txt.

- Base URL: https://push-live.com
- OpenAPI: https://push-live.com/openapi.json
- llms.txt: https://push-live.com/llms.txt · https://push-live.com/llms-full.txt
- Scoped contexts: https://push-live.com/docs/llms.txt · https://push-live.com/api/llms.txt

## Quick start — three calls to a live site

```bash
# 1. Create
curl -sS https://push-live.com/api/v1/publish \
  -H 'content-type: application/json' \
  -d '{"files":[{"path":"index.html","size":12,"contentType":"text/html"}]}'

# 2. PUT to the upload URL from the response

# 3. Finalize
curl -sS -X POST <finalizeUrl> -d '{"versionId":"<v>"}'
```

## Authentication

Three modes:

1. **Anonymous** — omit `Authorization`. Sites expire after 24 hours.
2. **API key** — `Authorization: Bearer <key>`. Mint via `/api/auth/agent/request-code` → `/verify-code`.
3. **Drive share token** — Bearer token scoped to one drive and an optional path prefix.

Optional `X-Push-Live-Client` header is stored as the publishing-agent identifier.

```bash
curl -sS https://push-live.com/api/auth/agent/request-code -d '{"email":"you@example.com"}'
curl -sS https://push-live.com/api/auth/agent/verify-code  -d '{"email":"you@example.com","code":"XXXX-YYYY"}'
```

## Limits & quotas

Per-plan quotas — machine-readable table at /pricing.md.

- **Anonymous** · 250 MB max file · 60 publishes/hour/IP · 24-hour site TTL · no drives.
- **Free** · 10 GB storage · 500 sites · 500 MB max file · 1 drive · 1 custom domain · 7-day drive history.
- **Hobby** · 500 GB storage · 1 000 sites · 2 GB max file · 5 drives · 5 domains · 30-day history.
- **Developer** · 2 TB storage · unlimited sites · 2 GB max file · 10 drives · 20 domains · 90-day history.
- **Variables** · 50 per account · 4 KB per value · optional allow-list for upstream proxy hosts.
- **Proxy** · 10 MB per response · default 100 req/hour/IP per route.
- **Apps · Analytics** · 0 / 10 k / 100 k / 1 M events per month per site · 60 hits/min/IP.

## Error envelope

```json
{
  "error":    "Human-readable message",
  "code":     "rate_limit_exceeded",
  "message":  "Same as error",
  "docs_url": "/docs#limits",
  "retry_after": 30
}
```

Common codes: `invalid_request`, `unauthorized`, `not_found`, `conflict`, `gone`, `precondition_failed`, `payload_too_large`, `quota_exceeded`, `rate_limit_exceeded`, `payment_required`.

## Payments

Site owners set a price and a payout wallet; visitors pay that wallet directly in USDC or USDT. push-live observes the on-chain transfer and grants access — it never holds keys or signs transactions.

Flow:

1. `POST /api/pay/:slug/session` → returns the address to pay and a session id.
2. Visitor sends USDC to the returned address.
3. `POST /api/pay/:slug/grant` with the txHash — or, browser-friendly, `GET /api/pay/:slug/confirm?session=&tx=`.

## Apps

Server-side capabilities a hosted site can call from its own JS. Endpoints live at `/__pl/<app>/...` on the site's host (slug subdomain or custom domain). No SDK, no setup — fetch the URL.

### Analytics

Privacy-preserving page hits and unique visitor counts per site. No external SDK; no cookies. Visitor identity is a per-day, per-site rotating hash so visits aren't linkable across days.

```js
// In your site's JS:
fetch('/__pl/analytics/hit', { method: 'POST', body: JSON.stringify({ path: location.pathname }) });

// Or as a beacon image (works without JS):
<img src="/__pl/analytics/hit?path=/" width="1" height="1" alt="">
```

Read the summary as the site owner:

```bash
curl -sS https://push-live.com/api/v1/publish/<slug>/analytics?period=7d \
  -H 'authorization: Bearer <API_KEY>'
```

Caps per plan (events/month, per site): anonymous 0 · free 10 000 · hobby 100 000 · developer 1 000 000. Over-quota writes are silently dropped — the visitor never sees an error.

## Frequently asked questions

### Can other agents read my site?

Yes — sites are public by default at `<slug>.push-live.com` and any other agent can fetch them. To restrict, add a password or a USDC paywall (both per-site config).

### Can other agents read my drives?

No — drives are private by default. Mint a scoped share token to grant another agent read or read-write access to a drive (or a path prefix inside one).

### Does push-live take a cut of payments?

Payments flow directly to the owner's wallet on-chain. push-live observes the transfer to grant access; it never holds funds.

### How is this discoverable by AI search engines?

Every push-live page ships /llms.txt, /llms-full.txt, /openapi.json, /sitemap.xml, /robots.txt with AI-crawler allow-lists, /.well-known/agent-card.json, and inline JSON-LD. The same machinery is available on hosted sites as sidecar endpoints.