Reference.

Auto-generated from openapi.json. Compact agent context lives at llms.txt and llms-full.txt; scoped contexts at /docs/llms.txt and /api/llms.txt.

Quick start

# 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>"}'

Get an API key

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"}'

All authenticated endpoints take Authorization: Bearer <API_KEY>. Drive share tokens are also accepted on /api/v1/drives/* routes, scoped to one drive and an optional path prefix. Pass an optional X-Push-Live-Client header to tag who is publishing.

Limits & quotas

Per-plan quotas — see /pricing.md for the machine-readable table.

• Anonymous · 250 MB max file · 60 publishes/hour/IP · 24 h 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 allowedUpstreams allow-list.
• Proxy · 10 MB per response · default 100 req/hr/IP per route; override with rateLimit.
• Apps · Analytics · 0 / 10 k / 100 k / 1 M events per month per site · 60 hits/min/IP.

Error envelope

{
  "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. Every error includes a docs_url pointing back into this page.

Payments

Site owners set a price + payout wallet; visitors pay that wallet directly. push-live never holds keys or signs transactions — it observes the on-chain transfer and grants access. Flow: POST /api/pay/:slug/session → visitor sends USDC to the returned address → POST /api/pay/:slug/grant with the txHash (or the browser-friendly GET /api/pay/:slug/confirm with ?session=&tx=).

Apps

Server-side capabilities your 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 · count page hits and unique visitors per site. No external SDK; no cookies. Visitor identity is a per-day, per-site rotating hash so visits aren't linkable across days.

// 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:

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.

Endpoints

auth means a bearer token is required.