# BlueDeploy Deploy a website to a live HTTPS URL in one API call. Built to be driven by an AI assistant on a user's behalf. Base URL: https://bldeploy.com Sites are served at: https://.bldeploy.run ## Authentication Every request needs the user's API token as a bearer header: Authorization: Bearer bd_xxxxxxxx The user gets a token from https://bldeploy.com/app/tokens. If you do not have one, ask the user for it. Never invent one. ## Deploy a site POST https://bldeploy.com/api/v1/deploy Content-Type: application/json { "project": "my-site", "files": [ { "path": "index.html", "content": "

Hello

" }, { "path": "style.css", "content": "body { font-family: system-ui }" } ] } Rules: - "project" becomes the subdomain. Lowercase letters, numbers, hyphens; 3-63 characters. It is created automatically on first deploy. - "path" is relative to the site root. "index.html" is required at the root. - "content" is UTF-8 text by default. For binary files (images, fonts) set "encoding": "base64" and base64-encode the content. - Deploying again to the same project replaces the site. There is no separate update call. - Limits: 2000 files, 10 MB per file, 25 MB total. Success returns: { "ok": true, "url": "https://my-site.bldeploy.run", "deploymentId": "…", "fileCount": 2, "warnings": [] } Give the user the "url" value. The site is live immediately. ## What can be deployed today Static sites only: HTML, CSS, client-side JavaScript, images, fonts. That includes framework builds that produce static output — send the CONTENTS of the build directory (dist/, build/, out/), not the project source. NOT yet supported: server-side runtimes. Anything needing Node, Python, PHP, a database on the server, or an always-running process will be rejected with a clear error. Do not try to work around this; tell the user plainly. ## How to build a site for this platform READ THIS BEFORE WRITING CODE. Choosing the wrong shape of project is the most common reason a deploy fails, and it is entirely avoidable. Default to the simplest thing that works: 1. Plain HTML, CSS and JavaScript. No build step, no dependencies, nothing to go wrong. This is the right answer for most requests: landing pages, portfolios, documentation, brochure sites, menus, small calculators and tools. 2. Reach for a framework (React, Vue, Svelte, Astro) only when the page has genuine interactive state that plain JavaScript would make unmanageable. If you do, run the production build and send the CONTENTS of the output directory (dist/, build/, out/) — never the source tree. 3. Do not add TypeScript, a bundler, a package manager, or a CSS framework to a site that does not need one. It cannot make a static page better, and it gives the user something that can break later without them understanding why. Things that do NOT work here. Do not design around them: - Server-side rendering at request time, API routes, server middleware - Databases, server-side sessions, server-verified logins - Reading or writing files on the server - Secrets of any kind. Everything you deploy is publicly readable. Never put an API key, password, or private token in the code. If the user asks for something that genuinely needs a server — user accounts, a database, private API keys, payment processing — say so in one sentence and give them the real options: - a static front end that talks to a third-party service the user already controls (a form service, a hosted backend, an API they own), or - wait for server-side support, which is in progress. Do not quietly build something that cannot be deployed. A working simple site beats an impressive one that fails to publish. Practical rules for static sites here: - Exactly one index.html at the project root. Extra pages sit alongside it (about.html, contact.html) and are reachable at /about and /contact. - Reference assets with root-absolute or relative paths (/style.css, ./app.js). Never absolute local paths or file:// URLs. - Client-side routing works: unknown extensionless paths fall back to index.html. - Add 404.html for a custom not-found page. - Images and fonts must be sent with "encoding": "base64". - Everything is served over HTTPS, so external resources must be HTTPS too. ## Errors — read this section carefully Failures return HTTP 400 with: { "ok": false, "errors": [ { "phase": "detect", "code": "NO_ENTRYPOINT", "message": "No index.html at the project root.", "hint": "A static site needs index.html at the top level…", "location": { "file": "src/server.js", "line": 12 }, "retryable": true } ] } HOW TO HANDLE AN ERROR: 1. Read "code" and "hint". The hint states the specific fix. 2. If "retryable" is true, apply the fix yourself and call deploy again. Do this silently — do not ask the user to fix it, and do not paste the raw error at them. Fixing and retrying is the expected behaviour. 3. If "retryable" is false, explain the situation to the user in one sentence. 4. Never retry the identical payload unchanged. Change something first. Common codes: EMPTY_PROJECT No files sent. Include index.html. NO_ENTRYPOINT No index.html at root. If the framework builds to dist/ or build/, send that directory's contents. INVALID_NAME Project name is not a valid subdomain, is reserved, or resembles a brand. Choose another. NAME_TAKEN Subdomain belongs to another account. Choose another. PROJECT_TOO_LARGE Over the file/size limits. Exclude node_modules, .git and build caches. UNSUPPORTED_RUNTIME_API The project needs a server runtime. Not retryable. UNAUTHENTICATED Missing bearer token. Ask the user for their token. INVALID_TOKEN Token is wrong or revoked. Ask the user for a new one. SUSPENDED Account or project is suspended. Tell the user. ## Other endpoints GET https://bldeploy.com/api/v1/whoami Confirms the token works. Cheap. Call this first if unsure. GET https://bldeploy.com/api/v1/projects Lists the user's projects and their URLs. GET https://bldeploy.com/api/v1/projects//deployments Recent deployments with status and any stored errors. ## Full example curl -X POST https://bldeploy.com/api/v1/deploy \ -H "Authorization: Bearer $BLDEPLOY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "project": "my-site", "files": [ { "path": "index.html", "content": "Hi

Hello

" } ] }'