Deploy Endpoints

Create Deployment

POST /deploy

Deploy a site to a live URL. Supports single HTML file or multi-file site.

Authentication: Required.

Request body:

Field	Type	Required	Description
`html`	`string`	No*	Full HTML content for single-file deploys
`files`	`array`	No*	Files for multi-file deploys
`slug`	`string`	No	Custom URL slug (lowercase, hyphens only). Auto-generated if omitted.
`title`	`string`	No	Page title
`description`	`string`	No	Meta description
`favicon`	`string`	No	Favicon emoji. For multi-file deploys, include a `favicon.ico` file instead.
`og_image`	`string`	No	Custom Open Graph image URL. For multi-file deploys, include an `og-image.png` file instead.
`is_spa`	`boolean`	No	Enable 404→index.html fallback for SPA routing
`protect`	`boolean`	No	Make the page private. Returns a `share_url` token link that grants access automatically.
`password`	`string`	No	Add a typed-password gate as a fallback for visitors without the share link. Requires `protect: true`.

*Either html or files is required.

`files` array format

json

[
  {
    "path": "index.html",
    "content": "<html>...</html>",
    "contentType": "text/html"
  },
  {
    "path": "css/style.css",
    "content": "body { ... }",
    "contentType": "text/css"
  },
  {
    "path": "images/logo.png",
    "content": "iVBORw0KGgo...",
    "contentType": "image/png",
    "encoding": "base64"
  }
]

Single-file example:

bash

curl -X POST https://api.based.page/deploy \
  -H "Authorization: Bearer bp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello World</h1>", "slug": "my-page", "title": "Hello"}'

Response (200):

json

{
  "id": "dep_abc123",
  "slug": "my-page",
  "url": "https://my-page.based.page"
}

For protected pages, the response also includes a share_url:

json

{
  "id": "dep_abc123",
  "slug": "my-page",
  "url": "https://my-page.based.page",
  "share_url": "https://my-page.based.page/?_token=xxx"
}

Errors: 400 (missing/invalid fields), 401 (invalid API key), 409 (slug conflict), 403 (deployment limit reached)

Get Status

GET /deploy/:id

Retrieve deployment metadata.

Authentication: Required.

Example:

bash

curl https://api.based.page/deploy/dep_abc123 \
  -H "Authorization: Bearer bp_your_api_key"

Response (200):

json

{
  "id": "dep_abc123",
  "slug": "my-page",
  "url": "https://my-page.based.page",
  "status": "active",
  "storage_type": "html",
  "is_spa": false,
  "title": "My Page",
  "description": null,
  "favicon": "⚡",
  "created_at": "2026-03-01T10:30:00Z",
  "updated_at": "2026-03-01T14:22:00Z"
}

Errors: 401 (unauthorized), 404 (not found)

Update Deployment

PUT /deploy/:id

Replace the content of an existing deployment. The URL and slug remain unchanged.

Authentication: Required.

Request body:

Same fields as POST /deploy, except slug cannot be changed here (use PATCH /deploy/:id/slug to rename). Pass html or files (but not both). All other fields are optional - omit to keep existing values.

Additional fields for password management:

Field	Type	Required	Description
`protect`	`boolean`	No	`true` to enable private access, `false` to remove all protection.
`password`	`string`	No	Set or update the password gate.
`remove_password`	`boolean`	No	`true` to remove the password fallback (page stays protected via share link if `protect` is still active).

Example:

bash

curl -X PUT https://api.based.page/deploy/dep_abc123 \
  -H "Authorization: Bearer bp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Updated Content</h1>"}'

Response (200):

json

{
  "id": "dep_abc123",
  "slug": "my-page",
  "url": "https://my-page.based.page"
}

Errors: 400 (missing/invalid fields), 401 (unauthorized), 404 (not found)

Rename Slug

PATCH /deploy/:id/slug

Change the URL slug of an existing deployment. The content stays the same; the subdomain changes immediately. The old URL stops working.

Authentication: Required.

Request body:

Field	Type	Required	Description
`slug`	`string`	Yes	New slug (lowercase, hyphens, globally unique)

Example:

bash

curl -X PATCH https://api.based.page/deploy/dep_abc123/slug \
  -H "Authorization: Bearer bp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-new-slug"}'

Response (200):

json

{
  "id": "dep_abc123",
  "slug": "my-new-slug",
  "url": "https://my-new-slug.based.page"
}

Errors: 400 (invalid slug), 401 (unauthorized), 404 (not found), 409 (slug already taken)

Delete Deployment

DELETE /deploy/:id

Delete a deployment. The page goes offline immediately and the slug is freed.

Authentication: Required.

Example:

bash

curl -X DELETE https://api.based.page/deploy/dep_abc123 \
  -H "Authorization: Bearer bp_your_api_key"

Response (200):

json

{
  "id": "dep_abc123",
  "message": "Deployment deleted successfully."
}

Errors: 401 (unauthorized), 404 (not found)

List Deployments

GET /deploys

List all active deployments for the authenticated user.

Authentication: Required.

Response (200):

json

{
  "deployments": [
    {
      "id": "dep_abc123",
      "slug": "my-page",
      "url": "https://my-page.based.page",
      "title": "My Page",
      "updated_at": "2026-03-01T14:22:00Z"
    }
  ]
}

Errors: 401 (unauthorized)

Notes

Slug rules: lowercase, hyphens only, globally unique. Single-word slugs are reserved - use a hyphenated slug (e.g. my-site).
Deletion frees up a slot against your plan limit.
Multi-file updates via PUT replace all existing files with the new set.
Protected pages return a share_url - send this to recipients for automatic access. Visitors without the link see a password gate if a password is set, or a 403 otherwise.
Renaming a slug changes the live URL immediately. The old subdomain is released and may be claimed by others.

Deploy Endpoints ​

Create Deployment ​

files array format ​

Get Status ​

Update Deployment ​

Rename Slug ​

Delete Deployment ​

List Deployments ​

Notes ​

Deploy Endpoints

Create Deployment

`files` array format

Get Status

Update Deployment

Rename Slug

Delete Deployment

List Deployments

Notes