Quick start in 60 seconds

Paste HTML below and deploy it live. Your agent gets back an HTTPS URL immediately — no account, no config.

Try it now

Paste HTML below. Click Deploy it live → and get a real live URL in under a second.

▸ interactive deploy Paste HTML → hit deploy → get a live URL
HTML
API key
$ curl -s -X POST https://pages.rosabuilds.com/api/upload \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"path":"index.html","content":"BASE64"}]}'

Quickstart

Get from zero to a live URL in under 2 minutes.

1. Get your API key

Visit pages.rosabuilds.com/dashboard, enter your API key, and start deploying. The default agent key is pages_agent_Kx9mR4pQ3w.

2. Deploy a file

# Base64-encode your HTML and POST it
$ CONTENT=$(base64 -w0 index.html 2>/dev/null || base64 index.html)
$ curl -s -X POST https://pages.rosabuilds.com/api/upload \
     -H "x-api-key: $PAGES_API_KEY" \
     -H "Content-Type: application/json" \
     -d "{\"files\":[{\"path\":\"index.html\",\"content\":\"$CONTENT\"}]}" \
  | jq -r .url

# Response:
https://a3f9c12e.pages.rosabuilds.com
import requests, base64, os

html = "<h1>Hello from my agent</h1>"
content = base64.b64encode(html.encode()).decode()

resp = requests.post(
    "https://pages.rosabuilds.com/api/upload",
    headers={"x-api-key": os.environ["PAGES_API_KEY"]},
    json={"files": [{"path": "index.html", "content": content}]},
)
url = resp.json()["url"]
print(url)  # https://a3f9c12e.pages.rosabuilds.com

# Multi-file deploy
resp = requests.post(
    "https://pages.rosabuilds.com/api/upload",
    headers={"x-api-key": os.environ["PAGES_API_KEY"]},
    json={"files": [
        {"path": "index.html", "content": base64.b64encode(html_bytes).decode()},
        {"path": "style.css",  "content": base64.b64encode(css_bytes).decode()},
    ]},
)
const html = `<!DOCTYPE html><h1>Hello from my agent</h1>`;
const content = Buffer.from(html).toString('base64');

const res = await fetch('https://pages.rosabuilds.com/api/upload', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAGES_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    files: [{ path: 'index.html', content }],
  }),
});
const { url, id } = await res.json();
console.log(url); // https://a3f9c12e.pages.rosabuilds.com

Response

json 
{
  "url": "https://a3f9c12e.pages.rosabuilds.com",
  "id":  "a3f9c12e"
}

Authentication

All write API requests must include your API key in the x-api-key header.

http header 
x-api-key: pages_agent_Kx9mR4pQ3w

Keep your key secret. Never expose it in client-side code or commit it to version control. Use environment variables: export PAGES_API_KEY=pages_agent_...

The GET /api/stats and GET /api/health endpoints are public — no auth required.

Base URL

BASE https://pages.rosabuilds.com/api

All responses are JSON. Requests with a body should use Content-Type: application/json (for base64 JSON uploads) or multipart/form-data (for direct file uploads).

POST /api/upload

Deploy files and get an instant HTTPS URL. Accepts JSON with base64-encoded files or multipart form data.

POST /api/upload

JSON body (recommended for agents)

FieldTypeDescription
files required array Array of file objects: [{path: "index.html", content: "BASE64"}]. Content must be base64-encoded.

Multipart form (for file uploads)

FieldTypeDescription
file required file One or more files to deploy. Use multiple -F file=@filename for multifile. Max 100 MB total.

Response

url string Live HTTPS URL of the deployed site. Immediately accessible.
id string 8-character hex site ID. Use with update and delete endpoints.

POST /api/update/:id

Replace all files in an existing site. Same URL is preserved. Useful for iterative agent workflows.

POST /api/update/:id
bash 
$ curl -X POST https://pages.rosabuilds.com/api/update/a3f9c12e \
  -H "x-api-key: $PAGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[{"path":"index.html","content":"NEW_BASE64"}]}'

GET /api/sites

List all deployed sites for your API key, sorted by most recent first.

GET /api/sites
bash 
curl https://pages.rosabuilds.com/api/sites \
  -H "x-api-key: $PAGES_API_KEY"

Response

json
[
  {
    "id":           "a3f9c12e",
    "url":          "https://a3f9c12e.pages.rosabuilds.com",
    "file_count":   3,
    "size_bytes":   14820,
    "created_at":   1741392000,
    "updated_at":   1741392000
  }
]

DELETE /api/sites/:id

Immediately delete a site. The URL stops serving within seconds. Permanent — slug is released.

DELETE /api/sites/:id
bash 
curl -X DELETE https://pages.rosabuilds.com/api/sites/a3f9c12e \
  -H "x-api-key: $PAGES_API_KEY"

GET /api/stats

Public stats endpoint — no authentication required. Returns platform-wide metrics.

GET /api/stats
json — response
{
  "sites":          42,
  "total_deploys":  42,
  "pages_live":     42,
  "uptime_seconds": 86400
}

GET /api/health

Health check endpoint. Returns server status and current site count.

GET /api/health
json — response
{ "status": "ok", "sites": 42 }

File formats

Two upload modes are supported:

ModeContent-TypeFormatBest for
JSON + base64 application/json {"files":[{"path":"...","content":"BASE64"}]} AI agents, programmatic use
Multipart multipart/form-data -F "file=@index.html" (one or more) Shell scripts, direct file uploads

Multi-file tip: You can deploy entire sites with multiple files — HTML, CSS, JS, images — in one call. Just include all files in the files array. Each file is served at its path on the subdomain.

Error codes

All errors return JSON with an error field describing the problem.

json — error response
{ "error": "Missing x-api-key header" }
HTTPCauseDescription
400no filesRequest body has no files array, or all files are empty.
400bad contentA file's content field is not valid base64.
401unauthorizedMissing or invalid x-api-key header.
403forbiddenAPI key doesn't own the site you're trying to modify.
404not foundSite ID doesn't exist or was already deleted.
413too largeUpload exceeds the 50 MB request body limit.
500internal errorServer error. Retry with exponential backoff.

Rate limits

Currently no enforced rate limits — the server runs on dedicated infrastructure. Reasonable use expected.

PlanDeploys / dayMax uploadConcurrent
Free1010 MB per deploy1
Pro ($9/mo)Unlimited100 MB per deploy10
Team ($29/mo)Unlimited500 MB per deploy50

SDKs & snippets

The API is simple enough that you don't need an SDK. Here are copy-paste snippets for common runtimes.

Python — one-liner deploy function

python 
import requests, base64, os

def deploy(html: str, api_key: str = None) -> str:
    """Deploy HTML string and return live URL."""
    key = api_key or os.environ["PAGES_API_KEY"]
    content = base64.b64encode(html.encode()).decode()
    r = requests.post(
        "https://pages.rosabuilds.com/api/upload",
        headers={"x-api-key": key},
        json={"files": [{"path": "index.html", "content": content}]},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["url"]

# Usage
url = deploy("<h1>Hello</h1>")
print(url)  # https://a3f9c12e.pages.rosabuilds.com

Node.js — deploy utility

javascript 
// deploy.js — works in Node 18+ (native fetch)
export async function deploy(html, apiKey = process.env.PAGES_API_KEY) {
  const content = Buffer.from(html).toString('base64');
  const res = await fetch('https://pages.rosabuilds.com/api/upload', {
    method: 'POST',
    headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ files: [{ path: 'index.html', content }] }),
  });
  if (!res.ok) throw new Error(await res.text());
  return (await res.json()).url;
}

// Usage
const url = await deploy(`<h1>Hello</h1>`);
console.log(url);

Agent examples

Claude agent — deploy a report as a tool

python 
import anthropic, requests, base64, os

client = anthropic.Anthropic()

def deploy_html(html: str) -> str:
    content = base64.b64encode(html.encode()).decode()
    r = requests.post(
        "https://pages.rosabuilds.com/api/upload",
        headers={"x-api-key": os.environ["PAGES_API_KEY"]},
        json={"files": [{"path": "index.html", "content": content}]},
    )
    return r.json()["url"]

tools = [{
    "name": "deploy_page",
    "description": "Deploy an HTML page and return its live HTTPS URL",
    "input_schema": {
        "type": "object",
        "properties": {"html": {"type": "string"}},
        "required": ["html"]
    }
}]

msg = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=tools,
    messages=[{"role": "user",
               "content": "Write a beautiful HTML page summarising the top AI trends of 2026 and deploy it."}],
)

Shell pipeline — build, deploy, open

bash 
# Build, encode, deploy, open — all in one line
URL=$(CONTENT=$(base64 -w0 index.html 2>/dev/null || base64 index.html) && \
  curl -s -X POST https://pages.rosabuilds.com/api/upload \
    -H "x-api-key: $PAGES_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"files\":[{\"path\":\"index.html\",\"content\":\"$CONTENT\"}]}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")

echo "Live at: $URL"
open "$URL"  # macOS — opens in browser

Webhooks (Pro+)

Pro and Team accounts can register a webhook URL to receive events on every deploy, deletion, or expiry. Configure from the dashboard when available.

json — webhook payload
{
  "event":     "deploy.created",
  "site_id":   "a3f9c12e",
  "url":       "https://a3f9c12e.pages.rosabuilds.com",
  "timestamp": 1741392000
}

Questions? Open an issue on GitHub or email hi@rosabuilds.com.