Novence

Documentation

Ship with Novence

Live API https://api.novence.ai. Static sites only. Agents and humans use the same control plane.

Start with CLI or SDK

# Fastest path — no install
npx novence deploy ./dist

# TypeScript
npm install @novence/sdk

# Python 3.10+, no dependencies
pip install novence

CLI uploads, checks, publishes, and prints the live URL. First run with no key publishes anonymously — claim with novence claim --email afterwards. Typed clients: /cli and /sdk. Raw REST below if you need the HTTP loop.

1. Bootstrap (deploy on trial; OTP after live URL)

curl -s -X POST https://api.novence.ai/v1/bootstrap \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'

# Save apiKey. Deploy on unverified trial — do not wait for OTP.
# AFTER the live URL, verify OTP from email (expires in 15 minutes):
curl -s -X POST https://api.novence.ai/v1/auth/verify-email \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","code":"123456"}'

# Resend: POST /v1/auth/resend-verification  → { sent: true } even if already verified
# Lost key: same OTP → POST /v1/auth/reissue-key (also verifies email; do not also call verify-email)

Unverified trial still publishes (tight caps; checks may be skipped). OTP codes expire in 15 minutes. Checkout and full free quotas require a verified email — ask for the code after the live URL.

2. Deploy loop

  1. One HTML file: POST /v1/publish-html or MCP publish_html — writes /index.html and deploys. Then poll as below. CLI: npx novence deploy report.html. See /artifacts.
  2. POST /v1/projects → project.id, project.suffix, project.url. Project status is lifecycle (active), not deploy state.
  3. Upload (confirm required; contentType optional). Prefer batch: POST …/uploads/batch → PUT → POST …/uploads/confirm-batch
  4. POST …/deployments → then poll GET …/deployments/latest until deployment.status is live or failed
  5. Read quality checks from checksResults or GET …/checks
  6. Open https://{suffix}.novence.ai/

Prefer usage.storage_bytes over rounded storage_gb. {suffix}.novence.ai is a share URL (noindex). On a custom domain, uploaded robots.txt is authoritative. Cookieless traffic: see /analytics, GET /v1/projects/{id}/analytics or MCP get_project_analytics (off by default; enable with MCP update_project_settings analytics_enabled true. Pageviews, 404s, referrers, countries. No cookies, 90-day retention).

Whole flow in one command: npx novence deploy ./dist — see /cli. Framework how-tos (Next.js static export, Astro, Hugo, …): /guides. Typed clients: npm install @novence/sdk or pip install novence — /sdk. Same plane, raw HTTP above.

3. Custom domains

Verified Free includes 1 domain; Pro/Scale include more (soft overage $1/domain-mo). Call POST /v1/projects/{id}/domains with your hostname (default primary = www). Then DNS:

TypeHostValue
CNAMEwwwfallback.novence.ai
ALIAS or URL redirect@ (apex)fallback.novence.ai or https://www.yourdomain/ — do exactly one

Required: www CNAME. Then pick one apex option (ALIAS/flattening, or registrar URL-redirect). Poll dns.next until null. Search engines index the custom domain, not {suffix}.novence.ai.

4. Forms (optional)

Contact forms are optional. Use Novence Forms or a BYO backend (Formspree, Web3forms, custom action URL). Sites do not need a Novence form resource to go live.

Novence Forms:

  1. POST /v1/projects/{id}/forms with name + fields[] (email must be verified)
  2. Point the HTML form at action="/__forms/{formId}" (same-origin) or POST https://api.novence.ai/v1/public/forms/{formId}/submissions
  3. Include honeypot _gotcha. Submissions email the owner and appear in the local console-kit project view.

Quotas: Free 50/mo (hard); Pro 2,000 / Scale 20,000 included; Pro/Scale soft overage $0.005/submission. BYO backends do not count.

Widgets and data files (optional)

Static-only is not a dead end. There is no plugin marketplace. Improve hosted sites in the files you upload. Full page: /site-data.

Third-party widgets:

Paste a script or iframe (Cal.com, Snipcart, Shopify Buy Button, Stripe Payment Links, GA, Formspree). HTML is served as-is — Novence does not strip tags. Never put nv_ keys in the page.

Baked-in data files:

Upload /data/{collection}.json (.json is allowlisted). Page JS fetches same-origin: fetch("/data/menu.json"). Use for hours, menus, team, services, FAQ, inventory. Free: update that file and deploy. Pro/Scale: PUT live with put_site_data (keep the file in the project). Cache ~60s. Do not store secrets.

Bookings and checkout: BYO widget. Contact leads: Novence Forms. WordPress PHP plugins and private CRM data: out of scope.

Team seats (Pro / Scale)

The project owner invites collaborators. Free is owner-only (HTTP 402). Pro includes 5 extra seats per project; Scale 20. Deploys and storage still bill the owner. create_project always creates on the caller's account — collab uses an existing project_id.

  1. POST /v1/projects/{id}/members with email + role (viewer / editor / admin). Only the owner may invite admin.
  2. Invitee opens https://novence.ai/invite, verifies email OTP, and saves the project-scoped nv_ key shown once.
  3. MCP: invite_project_member / list_project_members / leave_project. Never share the owner key.

5. Account console (local)

There is no hosted Novence dashboard. Agents write a local HTML file. Keep nv_ keys with the agent — never embed them in HTML, URLs, or git. The browser uses a short-lived mgmt_ token only (30 minutes; scopes account:read + billing:portal). Product overview and screenshots: /dashboard.

  1. GET /v1/account/console-kit (Bearer nv_) — snapshot + HTML template + serve instructions
  2. POST /v1/account/sessions → mgmt_ token
  3. Write novence-console.html, store the token in sessionStorage only
  4. Serve on http://127.0.0.1 (not file://) for live refresh
# Kit + session (keep $KEY out of the HTML file)
curl -s https://api.novence.ai/v1/account/console-kit -H "authorization: Bearer $KEY"
curl -s -X POST https://api.novence.ai/v1/account/sessions -H "authorization: Bearer $KEY"

# Refresh / read account with the browser token
curl -s https://api.novence.ai/v1/account -H "authorization: Bearer $MGMT"

# Humans without an agent: email OTP
curl -s -X POST https://api.novence.ai/v1/account/sessions/request \
  -H 'content-type: application/json' -d '{"email":"you@example.com"}'
curl -s -X POST https://api.novence.ai/v1/account/sessions/verify \
  -H 'content-type: application/json' -d '{"email":"you@example.com","code":"123456"}'

# Serve locally
python3 -m http.server 8765 --bind 127.0.0.1
# → http://127.0.0.1:8765/novence-console.html

Console UI: plan, verification, quotas vs usage, projects + live URLs, Refresh, Manage billing (portal), Log out. MCP: get_account_console_kit. Alias quotas: GET /v1/billing/quotas.

6. Billing

Checkout (subscription)

curl -s -X POST https://api.novence.ai/v1/billing/checkout \
  -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"plan":"pro"}'
# → { "url": "https://checkout.stripe.com/…" }

Creates a Stripe subscription with licensed price + metered overages on one monthly invoice. Stripe emails invoices and receipts to the account email; the Customer Portal has PDFs. Success/cancel pages: /billing/success, /billing/cancel.

Customer Portal (cancel / payment method)

curl -s -X POST https://api.novence.ai/v1/billing/portal \
  -H "authorization: Bearer $MGMT_OR_KEY" \
  -H 'content-type: application/json' \
  -d '{"returnUrl":"https://novence.ai/docs#billing"}'
# → { "url": "https://billing.stripe.com/…" }

Accepts nv_ or mgmt_ with billing:portal. Hosted by Stripe — cancel, update payment method, view invoices.

MPP (agent subscription)

curl -i -X POST https://api.novence.ai/v1/billing/mpp \
  -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"plan":"pro"}'
# → HTTP 402 + WWW-Authenticate: Payment …
# Complete with SPT (e.g. npx @stripe/link-cli mpp pay …)

Creates the same monthly Pro/Scale subscription as Checkout. First month is charged via SPT; renewals continue until cancelled. Metered overages apply on the invoice.

References