> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.embeddables.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hosting Admin SDK
> Manage hosting projects, apps, deploy keys, previews, production, and domains with @embeddables/admin
Hosting methods are available on the authenticated `@embeddables/admin` client. Reads require
`project.read`; writes require `project.write`.
## Install
```bash npm theme={null}
npm install @embeddables/admin
```
```bash pnpm theme={null}
pnpm add @embeddables/admin
```
```bash yarn theme={null}
yarn add @embeddables/admin
```
Example:
```typescript theme={null}
import { initAdmin } from '@embeddables/admin'
const admin = initAdmin()
await admin.requestOtp({ email: 'operator@example.com' })
await admin.verifyOtp({ email: 'operator@example.com', token: '123456' })
```
## Project and apps
Project UUID.
`{ slug, enrolled, app_count }`.
Project UUID.
A 3–16 character hosting slug.
Updated enrollment.
Project UUID.
Registered apps.
Project UUID.
A unique 3–12 character app slug.
Optional repository path.
Git branch to auto-promote; defaults to `main`.
Created app.
Project UUID.
Hosting app UUID.
New repository path.
New production branch. Its latest deploy is promoted when the value changes and a deploy exists.
Updated app.
Project UUID.
Hosting app UUID.
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
Project UUID.
`{ id, prefix, secret, created_at }`.
Project UUID.
Key ids, prefixes, creation, revocation, and last-used timestamps.
Project UUID.
Deploy-key UUID.
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
Project UUID.
Git branch name.
Branch previews across the project's apps.
Project UUID.
Hosting app UUID.
1–100; defaults to 20.
Commit builds, newest first.
What production serves now, even when outside the returned page.
Project UUID.
Hosting app UUID.
`{ production_label, script_name, updated_at }`.
Project UUID.
Hosting app UUID.
1–100.
Promotions, newest first.
Project UUID.
Hosting app UUID.
Branch or immutable commit preview label. Older commit labels support rollback.
`{ 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
Project UUID.
Hosting app UUID.
Domains and their current status.
Project UUID.
Hosting app UUID.
Full hostname, without a scheme or path.
Created domain in `pending` status.
Project UUID.
Hosting app UUID.
Hosting-domain UUID.
Confirms removal.
After you add a domain, follow the dashboard's DNS instructions. Embeddables activates it after
verification.
## Returns
`{ id, project_id, slug, repo_path, production_branch, created_at }`.
`{ id, project_id, app_id, hostname, status, cloudflare_hostname_id, verified_at, created_at }`.
Status is `pending`, `active`, or `failed`.
`{ label, url, app_slug, project_slug, ref }`. Production has a `null` ref.
Also includes `{ commit, committed_at, created_at, branches, is_production }`.
`{ 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` |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.