# OnePush — Instant web publishing for AI agents # https://onepu.sh ## Quick Start POST https://onepu.sh/api/v1/push Content-Type: application/json {"files": {"index.html": "...", "style.css": "..."}} Response (201): {"url": "https://your-site.onepu.sh", "slug": "...", "updateToken": "tok_...", "claimUrl": "https://onepu.sh/claim/..."} IMPORTANT: Save the "updateToken" from the response. You need it to update the site later. Show the user the live URL. If they want to keep it, share the claimUrl so they can enter their email and claim permanent ownership. If you can't make HTTP requests, open https://onepu.sh/new in the browser to publish manually. ## Authentication Optional. Without auth, sites are anonymous and expire in 24 hours. With an API key, sites are permanent and appear in the user's dashboard. Two ways to authenticate (use whichever your HTTP client supports): 1. Header (preferred): Authorization: Bearer sk_your_api_key 2. Body field (fallback): include "apiKey": "sk_your_api_key" in the JSON body API keys are found at https://onepu.sh/dashboard/settings ## POST /api/v1/push (Simple — inline content) Best for agent-generated HTML, dashboards, reports. Up to 10MB total. Request: { "files": {"index.html": "...", "style.css": "...", "app.js": "..."}, "slug": "my-site", // optional, auto-generated if omitted "url": "https://appsumo.onepu.sh/launch", // optional, use to update an existing site by its live URL "name": "My Site", // optional, defaults to slug "apiKey": "sk_your_api_key", // optional, alternative to Authorization header "updateToken": "tok_abc123..." // optional, for updating anonymous sites } Response (201): { "url": "https://slug.onepu.sh", "slug": "slug", "updateToken": "tok_abc123...", // SAVE THIS — needed for future updates "claimUrl": "https://onepu.sh/claim/token", // anonymous only "expiresIn": "24 hours" // anonymous only } ## Updating an Existing Site There are three ways to authorize an update: ### Option 1: API key (recommended for authenticated users) POST https://onepu.sh/api/v1/push Authorization: Bearer sk_your_api_key {"slug": "my-site", "files": {"index.html": "..."}} Or with API key in the body (if you can't set custom headers): POST https://onepu.sh/api/v1/push {"slug": "my-site", "apiKey": "sk_your_api_key", "files": {"index.html": "..."}} ### Option 2: updateToken (for anonymous agents or when you don't have an API key) POST https://onepu.sh/api/v1/push {"slug": "my-site", "updateToken": "tok_abc123...", "files": {"index.html": "..."}} ### Option 3: Update by URL (recommended when you know the live URL but not the slug) POST https://onepu.sh/api/v1/push {"url": "https://appsumo.onepu.sh/launch", "apiKey": "sk_your_api_key", "files": {"index.html": "..."}} The "url" field resolves the live URL to the correct underlying site slug automatically. IMPORTANT: The "updateToken" is returned in every push response (create and update). Always save it — it's the only way to update anonymous sites. Response: {"url": "https://my-site.onepu.sh", "slug": "my-site", "version": 2, "updated": true, "updateToken": "tok_abc123..."} The previous version is preserved and can be restored. ## URL Structure — Handles vs Slugs OnePush has two types of URLs. Understanding the difference prevents errors: 1. Direct slug URLs: https://my-site.onepu.sh - The subdomain IS the site slug - To update: use "slug": "my-site" 2. Handle URLs: https://appsumo.onepu.sh/launch - The subdomain ("appsumo") is a USER HANDLE, not a site slug - The path ("/launch") identifies the site under that handle - The actual site slug is something else (e.g. "bold-creek-hare") - To update: use "url": "https://appsumo.onepu.sh/launch" (the API resolves it) - Do NOT use "slug": "appsumo" — that will fail or create the wrong site When in doubt, use the "url" field with the full live URL. It always works. ## POST /api/v1/publish (Advanced — presigned uploads) For large files or binary assets (images, fonts, PDFs). Up to 250MB per file. Step 1 — Create site: POST https://onepu.sh/api/v1/publish { "files": [ {"path": "index.html", "size": 2048, "contentType": "text/html"}, {"path": "logo.png", "size": 51200, "contentType": "image/png"} ] } Response: { "slug": "slug", "url": "https://slug.onepu.sh", "uploads": [ {"path": "index.html", "uploadUrl": "https://presigned-url"}, {"path": "logo.png", "uploadUrl": "https://presigned-url"} ], "versionId": "v1", "updateToken": "tok_abc123..." } Step 2 — Upload each file: PUT {uploadUrl} Content-Type: {contentType} Body: raw file bytes Step 3 — Finalize: POST https://onepu.sh/api/v1/publish/{slug}/finalize {"versionId": "v1"} ## Site Settings PATCH https://onepu.sh/api/v1/sites/{slug}/settings Authorization: Bearer sk_your_api_key Updatable fields: - name (string) — display name - access_level — "public", "password", "team", or "draft" - password_hash (string) — password for protected sites - handle_path (string) — path under your handle Examples: {"access_level": "password", "password_hash": "secret"} {"access_level": "draft"} {"name": "My Project"} Response: {"ok": true} ## Deleting a Site DELETE https://onepu.sh/api/v1/sites/{slug}/settings Authorization: Bearer sk_your_api_key Permanently removes the site, all versions, and files. Cannot be undone. Response: {"ok": true} ## Claiming Anonymous Sites Anonymous publishes return a claimUrl. This is a one-time link. The user visits it, enters their email, receives a magic link, and the site becomes permanently theirs. The claim token cannot be recovered — always show it to the user. ## All Endpoints POST /api/v1/push — Single-call publish (inline content) POST /api/v1/publish — Create site with presigned upload URLs POST /api/v1/publish/:slug/finalize — Mark a version as live PUT /api/v1/publish/:slug — Update existing site (new version) GET /api/v1/publish — List your sites (auth required) GET /api/v1/publish/:slug — Get site details DELETE /api/v1/publish/:slug — Delete a site (auth required) GET /api/v1/claim/:token — Validate a claim token POST /api/v1/claim/:token — Claim a site with email POST /api/v1/sites/:slug/restore — Restore a previous version (auth required) PATCH /api/v1/sites/:slug/settings — Update site settings (auth required) DELETE /api/v1/sites/:slug/settings — Delete a site permanently (auth required) ## Limits Anonymous: 24h expiry, 10MB inline, 250MB presigned Free (authenticated): permanent, 10 sites, 1GB storage, analytics, teams ## Full documentation: https://onepu.sh/docs