# Novence docs (markdown)

> Bootstrap, deploy, domains, forms, and billing for Novence static-site hosting.
> HTML docs: https://novence.ai/docs · Full agent brief: https://novence.ai/llms-full.txt · OpenAPI: https://novence.ai/openapi.yaml

## Product

Novence hosts **static HTML/CSS/JS only** (no SSR, no server routes, no databases). Agents and humans use the same control plane at `https://api.novence.ai`. Improve hosted sites with **third-party widgets** (Cal.com, Snipcart, Shopify Buy Button, GA — HTML is served as-is) and **baked-in data files** (`/data/menu.json` fetched same-origin). There is no plugin marketplace. Details: https://novence.ai/site-data

Live project URL shape: `https://{suffix}.novence.ai/` (share URL; not indexed). Attach a custom domain to rank in search.

## CLI (fastest path)

```bash
npx novence deploy ./dist
npx novence deploy report.html
```

Uploads the directory, runs checks, publishes, prints the live URL. First run
without a key publishes anonymously, then you claim with an email:

```bash
novence claim --email you@example.com
```

Or pass `--email` on first deploy to bootstrap immediately. The URL is the last
line on stdout and progress goes to stderr, so it pipes:
`URL=$(npx novence deploy ./dist)`.

Other commands: `novence open`, `novence checks`, `novence domains add <host>`,
`novence domains status`, `novence keys list|revoke`, `novence projects`,
`novence login`, `novence claim`, `novence whoami`. Full reference: https://novence.ai/cli
Use `--json` (implies `--no-input`) plus `NOVENCE_API_KEY` in CI.

## Framework how-tos

Build locally, then upload the static output. Novence does **not** run `npm build` or SSR.
Framework guides (Next.js static export, Astro, Hugo, Eleventy, Nuxt generate, …):
https://novence.ai/guides

The CLI auto-detects `dist`, `build`, `out`, `public`, `_site`. Pass the path for
Nuxt (`.output/public`), VitePress (`.vitepress/dist`), Remix (`build/client`),
or a plain HTML folder (`.`).

## SDKs

```bash
npm install @novence/sdk
```

Dual ESM/CommonJS, typed responses, defaults to `https://api.novence.ai`.
Full page: https://novence.ai/sdk

```bash
pip install novence
```

Python 3.10+, no dependencies. `wait_for_deployment()` polls until live.

## API keys

- `GET /v1/api-keys` — list. Returns `keyPrefix`, `scope`, `current`; never the
  key or its hash. `?projectId=`, `?includeRevoked=true`.
- `DELETE /v1/api-keys/{id}` — revoke. 409 if it is the key you are calling with;
  `?force=true` overrides (recover with `/v1/auth/reissue-key`).

## Bootstrap & auth

1. `POST /v1/bootstrap` with `{ "email" }` → `{ apiKey, accountId, emailVerificationRequired }` — save `apiKey` and deploy on the unverified trial; do not wait for OTP
2. Deploy loop below (trial still publishes; checks may be skipped)
3. AFTER the live URL: email OTP (15 minutes). `POST /v1/auth/verify-email` with `{ "email", "code" }` to unlock Free
4. Resend: `POST /v1/auth/resend-verification` → `{ sent: true }` even if already verified
5. Lost key: `POST /v1/auth/reissue-key` with email + code — **also verifies email**; do not spend a second OTP on verify-email
6. Authorize project APIs with `Authorization: Bearer nv_live_…` (or `nv_test_…`)

Never put `nv_` keys in browser HTML, URLs, or git. MCP at `/mcp` does not need `Authorization` to start — call `bootstrap(email)`; the session adopts the key. Persist the `nv_` key in the client for later sessions.

## Deploy loop

1. **One HTML file:** `POST /v1/publish-html` `{ "html", "title"? }` (or MCP `publish_html`, or `npx novence deploy report.html`). Skip to poll.
2. Else `POST /v1/projects` → `{ project: { id, suffix, url, … } }`
3. Upload files (batch preferred): `POST …/uploads/batch` → PUT each → `POST …/uploads/confirm-batch`
4. `POST /v1/projects/{id}/deployments`
5. Poll `GET /v1/projects/{id}/deployments/latest` until `deployment.status` is `live` or `failed`
6. Read checks via `checksResults` or `GET /v1/projects/{id}/checks`
7. Open `project.url`

Project `status` is lifecycle (`active`), not deploy state — do not poll it for deploy readiness.

## Custom domains

Verified Free includes 1 domain; Pro/Scale include more (soft overage $1/domain-mo). Custom domains are the indexable origin; `{suffix}.novence.ai` is noindex.

`POST /v1/projects/{id}/domains` with hostname.

1. **Required:** CNAME `www` → `fallback.novence.ai`
2. **Do exactly one for apex:** ALIAS/ANAME/CNAME-flattening `@` → `fallback.novence.ai`, **or** registrar URL-redirect `@` → `https://www.{domain}/`

Poll `GET /v1/projects/{id}/domains` and follow `dns.next` until it is null. `customDomainStatus` stays pending after attach.

## Forms (optional)

- **Novence Forms:** `POST /v1/projects/{id}/forms`, then same-origin `POST /__forms/{formId}` or public API. Include honeypot `_gotcha`.
- **BYO:** Wire Formspree / Web3forms / custom action in static HTML.

## Widgets and data files (optional)

- **Third-party widgets:** Paste a script or iframe (Cal.com, Snipcart, Shopify Buy Button, Stripe Payment Links, GA). Novence does not strip tags. Never put `nv_` keys in HTML.
- **Baked-in JSON:** Upload `/data/{collection}.json` and `fetch("/data/menu.json")` same-origin. Free: update and deploy. Pro/Scale: `PUT /v1/projects/{id}/data/{name}` or MCP `put_site_data` (include the file in the next deploy). Do not store secrets. `.json` is allowlisted.
- Product: https://novence.ai/site-data

## Analytics

Cookieless HTML pageviews, 404s, referrers, and countries from the edge. **Off by default** — enable with `PATCH /v1/projects/{id}` `{ "analyticsEnabled": true }` or MCP `update_project_settings`. `GET /v1/projects/{id}/analytics` or MCP `get_project_analytics`. 90-day retention. Product: https://novence.ai/analytics

## Billing

- Quotas: `GET /v1/billing/quotas` or `GET /v1/account`
- Checkout: `POST /v1/billing/checkout` `{ "plan": "pro"|"scale" }`
- Portal: `POST /v1/billing/portal`
- MPP: `GET|POST /v1/billing/mpp` → HTTP 402 SPT

### Plans

| Plan | Price | Projects | Storage | Bandwidth/mo | Domains |
| --- | --- | --- | --- | --- | --- |
| Free | $0 | 1 | 1 GB | 10 GB | 1 |
| Pro | $29 | 20 | 50 GB | 200 GB | 10 |
| Scale | $149 | 125 | 250 GB | 1.5 TB | 100 |

## Team seats

Pro includes 5 extra collaborators per project; Scale 20. Free is owner-only (`402`). Invite: `POST /v1/projects/{id}/members`. Accept: https://novence.ai/invite (`POST /v1/invites/accept`). Each member gets their own project-scoped `nv_` key. `create_project` always bills the caller; collab uses `project_id`. Deploys count against the owner.

## Surfaces

- REST: `https://api.novence.ai/v1`
- GraphQL: `https://api.novence.ai/graphql`
- MCP: `https://api.novence.ai/mcp`
- Health: `https://api.novence.ai/health`

## Related

- [Guides](https://novence.ai/guides)
- [Claude Code](https://novence.ai/guides/claude-code) · [Cursor](https://novence.ai/guides/cursor) · [Grok Build](https://novence.ai/guides/grok-build)
- [Pricing](https://novence.ai/pricing)
- [MCP](https://novence.ai/mcp)
- [Examples](https://novence.ai/examples)
- [Artifacts](https://novence.ai/artifacts)
- [Widgets and data](https://novence.ai/site-data)
- [Analytics](https://novence.ai/analytics)
- [Compare](https://novence.ai/compare)
- [FAQ](https://novence.ai/faq)
- [llms.txt](https://novence.ai/llms.txt)
- [llms-full.txt](https://novence.ai/llms-full.txt)
- [Terms](https://novence.ai/terms)
- [Privacy](https://novence.ai/privacy)