Hosting Admin SDK

Hosting methods are available on the authenticated @embeddables/admin client. Reads require project.read; writes require project.write.

Install

npm install @embeddables/admin

pnpm add @embeddables/admin

yarn add @embeddables/admin

Example:

import { initAdmin } from '@embeddables/admin'

const admin = initAdmin()
await admin.requestOtp({ email: '[email protected]' })
await admin.verifyOtp({ email: '[email protected]', token: '123456' })

Project and apps

getHostingProject()

Read project hosting enrollment

string

required

Project UUID.

GetHostingProjectResult

{ slug, enrolled, app_count }.

enrollHostingProject()

Set the project slug once

string

required

Project UUID.

string

required

A 3–16 character hosting slug.

GetHostingProjectResult

Updated enrollment.

listHostingApps()

List registered apps

string

required

Project UUID.

HostingApp[]

Registered apps.

createHostingApp()

string

required

Project UUID.

string

required

A unique 3–12 character app slug.

string | null

Optional repository path.

string

Git branch to auto-promote; defaults to main.

HostingApp

Created app.

updateHostingApp()

Update app settings

string

required

Project UUID.

string

required

Hosting app UUID.

string | null

New repository path.

string

New production branch. Its latest deploy is promoted when the value changes and a deploy exists.

HostingApp

Updated app.

deleteHostingApp()

Delete an app and its domains

string

required

Project UUID.

string

required

Hosting app UUID.

true

Confirms deletion.

The project slug accepts 3–16 characters and the app slug 3–12 characters. Both use lowercase letters, numbers, and single hyphens. The project slug is set once, and app slugs do not change. production_branch defaults to main. Changing production_branch immediately promotes that branch’s latest deploy when one exists.

Deploy keys

createHostingDeployKey()

Create a CI deploy key

string

required

Project UUID.

CreateHostingDeployKeyResult

{ id, prefix, secret, created_at }.

listHostingDeployKeys()

List deploy-key metadata

string

required

Project UUID.

HostingDeployKey[]

Key ids, prefixes, creation, revocation, and last-used timestamps.

revokeHostingDeployKey()

Revoke a CI deploy key

string

required

Project UUID.

string

required

Deploy-key UUID.

true

Confirms revocation.

createHostingDeployKey is the only response that contains the plaintext edk_… secret. Store it immediately. listHostingDeployKeys returns only the key id, prefix, creation and revocation timestamps, and last-used timestamp.

Previews and production

listHostingPreviews()

List previews for one git branch

string

required

Project UUID.

string

required

Git branch name.

HostingPreview[]

Branch previews across the project’s apps.

listHostingDeploys()

List an app's commit builds

string

required

Project UUID.

string

required

Hosting app UUID.

number

1–100; defaults to 20.

HostingDeploy[]

Commit builds, newest first.

HostingPreview & { script_name: string } | null

What production serves now, even when outside the returned page.

getHostingProduction()

Read the production alias

string

required

Project UUID.

string

required

Hosting app UUID.

GetHostingProductionResult

{ production_label, script_name, updated_at }.

listHostingPromotions()

List production changes

string

required

Project UUID.

string

required

Hosting app UUID.

number

1–100.

HostingPromotion[]

Promotions, newest first.

promoteHostingPreview()

Promote a preview to production

string

required

Project UUID.

string

required

Hosting app UUID.

string

required

Branch or immutable commit preview label. Older commit labels support rollback.

PromoteHostingPreviewResult

{ production_label, script_name }.

Deploy and promotion limits accept 1–100. Deploys default to 20. Manual promotion can select an older immutable commit preview for rollback.

Custom domains

listHostingDomains()

List custom domains

string

required

Project UUID.

string

required

Hosting app UUID.

HostingDomain[]

Domains and their current status.

addHostingDomain()

string

required

Project UUID.

string

required

Hosting app UUID.

string

required

Full hostname, without a scheme or path.

HostingDomain

Created domain in pending status.

removeHostingDomain()

Remove a custom domain

string

required

Project UUID.

string

required

Hosting app UUID.

string

required

Hosting-domain UUID.

true

Confirms removal.

After you add a domain, follow the dashboard’s DNS instructions. Embeddables activates it after verification.

Returns

object

{ id, project_id, slug, repo_path, production_branch, created_at }.

object

{ id, project_id, app_id, hostname, status, cloudflare_hostname_id, verified_at, created_at }. Status is pending, active, or failed.

object

{ label, url, app_slug, project_slug, ref }. Production has a null ref.

HostingPreview

Also includes { commit, committed_at, created_at, branches, is_production }.

object

{ id, from_script_name, to_script_name, source_label, trigger, created_at }.

Errors

All SDK failures extend AdminError.

When	Error
A hosting method is called before OTP verification or session adoption	`ConfigError`
The session is missing, invalid, or expired	`ApiError` with status `401`
A slug, hostname, UUID, branch, label, or limit is invalid	`ApiError` with status `400`
The operator is not a project member or lacks `project.read` / `project.write`	`ApiError` with status `403`
A project, app, domain, deploy key, preview, or production alias is missing	`ApiError` with status `404`
A project slug is locked or taken, the project is not enrolled, or an app slug or hostname is already registered	`ApiError` with status `409`

Get Started

Hosting

SDKs

Install

Project and apps

Deploy keys

Previews and production

Custom domains

Returns

Errors

​Install

​Project and apps

​Deploy keys

​Previews and production

​Custom domains

​Returns

​Errors

Install

Project and apps

Deploy keys

Previews and production

Custom domains

Returns

Errors