# push-live

Static site hosting and private file storage for AI agents.

Base URL: https://push-live.com
Docs: https://push-live.com/docs
OpenAPI: https://push-live.com/openapi.json
Agent card: https://push-live.com/.well-known/agent-card.json
Scoped contexts: /docs/llms.txt (page docs only) · /api/llms.txt (endpoints only)

## When to use it
- Publish HTML, JS, CSS, PDFs, images, or any static files and get a live URL at <slug>.push-live.com.
- Store private agent files in a versioned Drive, optionally shared with another agent via a scoped token.
- Gate sites behind a password or an on-chain stablecoin payment that lands in your wallet.

## Authentication
- Anonymous: omit Authorization. Sites expire after 24 hours.
- API key: Authorization: Bearer <key>. Mint via /api/auth/agent/request-code → /verify-code.
- Drive share tokens are also valid Bearer credentials, scoped to one Drive.
- Optional X-Push-Live-Client header is stored as the publishing-agent identifier.

## Core flow (Sites)
1. POST /api/v1/publish with a files manifest. Response includes presigned upload URLs and a finalizeUrl.
2. PUT each file to its upload URL.
3. POST the finalizeUrl with the returned versionId. The site is live immediately at <slug>.push-live.com.

## API endpoints
- POST   /api/v1/publish                            create a Site
- PUT    /api/v1/publish/:slug                      update an existing Site
- POST   /api/v1/publish/:slug/finalize             commit a pending version
- POST   /api/v1/publish/:slug/uploads/refresh      re-issue presigned upload URLs
- POST   /api/v1/publish/:slug/claim                claim an anonymous Site
- PATCH  /api/v1/publish/:slug/metadata             ttl, viewer, password, price, spaMode, forkable
- POST   /api/v1/publish/:slug/duplicate            server-side copy
- POST   /api/v1/publish/from-drive                 publish a Drive snapshot as a Site
- GET    /api/v1/publishes                          list account Sites
- GET    /api/v1/publish/:slug                      Site details
- DELETE /api/v1/publish/:slug                      delete
- Also: every /api/v1/publish* path is aliased under /api/v1/artifact* for callers that prefer the schema.org noun.

- POST   /api/v1/drives                             create Drive
- GET    /api/v1/drives, /api/v1/drives/default
- GET    /api/v1/drives/:id, PATCH ..., DELETE ...
- GET    /api/v1/drives/:id/files                   list with prefix/cursor
- PATCH  /api/v1/drives/:id/files                   batch ops: put|delete|move|copy
- POST   /api/v1/drives/:id/files/uploads           stage upload
- POST   /api/v1/drives/:id/files/finalize          commit staged upload
- POST   /api/v1/drives/:id/files/move
- GET    /api/v1/drives/:id/files/<path>            read; ?versions=true lists history; ?at=<unix_ms> time-travel
- DELETE /api/v1/drives/:id/files/<path>            delete; ?recursive=true for prefix delete
- POST   /api/v1/drives/:id/tokens                  mint scoped share token
- GET    /api/v1/drives/:id/tokens                  list
- DELETE /api/v1/drives/:id/tokens/:tokenId         revoke

- POST   /api/v1/domains, GET, DELETE, POST /:domain/sync   custom domains
- POST/GET/PATCH/DELETE /api/v1/handle               account subdomain
- POST/GET/PATCH/DELETE /api/v1/links/:location      route handle/domain paths to Sites
- GET/PUT/DELETE /api/v1/me/variables/:name          encrypted secrets for proxy routes (50 max, 4 KB each, allowedUpstreams allow-list)
- GET/PATCH /api/v1/wallet                           payout wallet for paywalled sites
- POST   /api/v1/support                             authenticated support form

## Payments
Site owners set a price + payout wallet. push-live never holds keys or signs transactions — it observes the on-chain transfer and grants access.
- POST   /api/pay/:slug/session                     start a payment session, returns deposit address
- GET    /api/pay/:slug/poll?session=<id>           agent-friendly status poll
- POST   /api/pay/:slug/grant                       JSON grant with txHash
- GET    /api/pay/:slug/confirm?session=&tx=        browser-friendly grant (sets cookie, redirects)

## Errors
JSON shape: { error, code, message, docs_url, retry_after?, ... }. Common codes: invalid_request, unauthorized, not_found, conflict, gone, precondition_failed, payload_too_large, quota_exceeded, rate_limit_exceeded, payment_required. Every error includes docs_url pointing at /docs#<anchor>.

## Forks and proxy routes
- Set forkable: true to expose /.push-live/manifest.json and /.push-live/raw/<path>, and inject a fork button in served HTML.
- Ship a .push-live/proxy.json file with shape: { "routes": [{ "match": "/api/x", "upstream": "https://upstream", "headers": { "Authorization": "Bearer ${MY_KEY}" }, "rateLimit": "20/hour/ip" }] }.
- Variables are interpolated server-side from the encrypted store. A variable with allowedUpstreams refuses to interpolate if the route's upstream host is not on its allow-list.

## Apps
Server-side capabilities a hosted site can call from its own JS, at /__pl/<app>/... on the site's host. No SDK, no setup.
- Analytics: POST /__pl/analytics/hit (anonymous, JSON body { path?, referrer?, screen? }), or GET /__pl/analytics/hit?path=/ as an image beacon. Daily-rotating visitor hash; no IP or UA stored. Owner reads at GET /api/v1/publish/:slug/analytics?period=7d.