# Novence — full agent / LLM briefing

> Complete API brief for shipping static sites with Novence. Live API: https://api.novence.ai
> Start with the curated index at https://novence.ai/llms.txt. OpenAPI: https://novence.ai/openapi.yaml (also via redirects from api.novence.ai).

## Product
Novence hosts static HTML/CSS/JS sites. Agents bootstrap an API key, upload files, deploy, run quality checks, and get a live URL at `https://{suffix}.novence.ai/`.

## Auth
- Bootstrap: `POST /v1/bootstrap` `{ "email": "…" }` → `{ apiKey, accountId, emailVerificationRequired }`
- Verify: `POST /v1/auth/verify-email` `{ "email", "code" }` — OTP expires in **15 minutes**
- Resend OTP: `POST /v1/auth/resend-verification` `{ "email" }`
- Lost key: `POST /v1/auth/reissue-key` `{ "email", "code" }` (after resend)
- All project APIs: `Authorization: Bearer nv_live_…` (or `nv_test_…`)
- **Never** put `nv_` keys in browser HTML, URLs, or git. For a local account console:
  1. `GET /v1/account/console-kit` (or MCP `get_account_console_kit`)
  2. `POST /v1/account/sessions` → short-lived `mgmt_` token (scopes: `account:read`, `billing:portal`)
  3. Write `novence-console.html` from **`htmlTemplate` as-is** (inject only snapshot + `mgmt_` — do not redesign). Serve on `http://127.0.0.1`; store `mgmt_` in sessionStorage only
  4. Click a project in the kit for `GET /v1/projects/{id}/usage`
  5. Humans without the agent: `POST /v1/account/sessions/request` + `/verify` with email OTP

## Account & billing UI (local only — no hosted dashboard)
- Snapshot: `GET /v1/account` (nv_ or mgmt_)
- Quotas alias: `GET /v1/billing/quotas`
- Stripe Customer Portal: `POST /v1/billing/portal` `{ "returnUrl"? }`
- Prefer `usage.storage_bytes` over `storage_gb` for exact accounting
- `quotas.checkRuns` = included **check minutes** / month (same unit as `usage.check_minutes`)

## Core loop
1. `POST /v1/projects` → `{ project: { id, suffix, url, … }, url }` — project `status` is lifecycle (`active`), **not** deploy state
2. Upload files (confirm is required; safe to retry):
   - Batch (preferred): `POST …/uploads/batch` → PUT each → `POST …/uploads/confirm-batch`
   - Single: `POST …/uploads` → PUT → `POST …/uploads/confirm`
   - `contentType` optional — inferred from extension when omitted
3. `POST /v1/projects/{id}/deployments` → returns `phase`, `checksUrl`, `checksResults` when ready
4. **Poll** `GET /v1/projects/{id}/deployments/latest` until `deployment.status` is `live` or `failed` (do **not** poll project `status`)
5. Read checks: response field `checksResults` or `GET /v1/projects/{id}/checks`
6. Open `https://{suffix}.novence.ai/` (also returned as `project.url`)

## robots.txt
Customer-uploaded `/robots.txt` is authoritative. Novence does **not** inject Cloudflare managed AI-crawler blocks. Site owners control crawl policy.

## Custom domains
Verified Free includes **1** domain; Pro/Scale include more (soft overage **$1**/domain-mo).
`POST /v1/projects/{id}/domains` with hostname. Required DNS:
1. CNAME `www` → `fallback.novence.ai`
2. Registrar URL redirect apex → `https://www.{domain}/`

## Forms (optional)
Contact/lead forms are **optional**. Choose one:

### Novence Forms
1. `POST /v1/projects/{id}/forms` `{ "name", "fields": [{ "name", "type", "required"? }] }` (email must be verified)
2. Point the site form at same-origin `POST /__forms/{formId}` **or** `POST https://api.novence.ai/v1/public/forms/{formId}/submissions` (JSON or urlencoded)
3. Include honeypot field `_gotcha` (hidden). Submissions stored + emailed to `notifyEmail` (default account email)
4. List: `GET …/forms/{formId}/submissions` (also in local console-kit project view)
5. Quotas: Free **50**/mo (hard); Pro **2,000** / Scale **20,000** included; Pro/Scale soft overage **$0.005**/submission

### BYO (Formspree, Web3forms, custom)
Wire `<form action="https://formspree.io/f/…">` (or similar) in static HTML. Novence only hosts the page — no platform submissions or form quota.

## 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; retry with `Authorization: Payment …`

### Plans
- Free: $0/mo — 1 project, 1 GB storage, 10 GB bandwidth/mo, 20 deploys/mo, 30 check minutes/mo, **1 custom domain**, **50 form submissions/mo** (after email verify). Other overages blocked (HTTP 402).
- Pro: $29/mo — 20 projects, 50 GB storage, 200 GB bandwidth/mo, 2,000 deploys/mo, 4,000 check minutes/mo, 10 custom domains, 2,000 form submissions/mo.
- Scale: $149/mo — 125 projects, 250 GB storage, 1.5 TB bandwidth/mo, 20,000 deploys/mo, 40,000 check minutes/mo, 100 custom domains, 20,000 form submissions/mo.

### Overage rates (Pro / Scale only)
| Meter | Unit | Price |
| --- | --- | --- |
| Storage | GB-month | $0.05 |
| Bandwidth | GB | $0.08 |
| Deploys | deploy | $0.05 |
| Check minutes | minute | $0.04 |
| Custom domains | domain-month | $1.00 |
| Form submissions | submission | $0.005 |

## Surfaces
- REST `/v1` (JSON errors on all paths)
- GraphQL `/graphql`
- MCP `/mcp` — marketing guide: https://novence.ai/mcp
- OpenAPI https://novence.ai/openapi.yaml
- Docs https://novence.ai/docs
- Pricing https://novence.ai/pricing
- Examples playbook https://novence.ai/examples
- Compare https://novence.ai/compare
- Health https://api.novence.ai/health

## CLI helper
`pnpm launch-site -- --dir ./mysite --email you@example.com`