# Naïve — a governed real-world agent profile for every agent

Naïve gives every AI agent its own **real-world agent profile**: a verified business
identity (KYC/EIN/formation), a spend-capped card, an inbox and phone number, and
(optionally) a place to run — provisioned per end-user, governed on every action,
and instantly revocable.

Works with the runtime you already use (Vercel Eve, AWS Bedrock AgentCore,
LangGraph, or your own loop): provision the agentProfile, pull its governed tools, and
run the agent anywhere. Every regulated action (a charge, a send, a refund) routes
through the Naïve governance gateway — spend caps, approvals, audit, and revoke —
no matter where the agent runs.

Underneath the agent profile are the primitives you can also use directly: email,
search, image/video generation, social, virtual cards, trading (brokerage),
identity verification, company formation, and more.

## Provision an agent profile (TypeScript)

```ts
import { Naive } from "@usenaive-sdk/server";
const naive = new Naive({ apiKey: process.env.NAIVE_SECRET_KEY });

// One governed agent profile per tenant — idempotent, async to fully verify.
const op = await naive.forUser(tenantId).provision("support", {
  idempotencyKey: `op:${tenantId}`,
});
const tools = await op.tools();   // drop into your agent / Eve / LangGraph
// await op.revoke();             // absolute: freeze card, halt sends, tear down
```

## How to Use

**Primary method: CLI** — Install and use the `@usenaive-sdk/cli` package.
**Fallback: MCP** — Connect via SSE if the CLI is unavailable.
**Last resort: REST API** — Call endpoints directly with `Authorization: Bearer nv_sk_...`

## Installing the CLI

```bash
npm install -g @usenaive-sdk/cli
# or use without installing:
npx @usenaive-sdk/cli <command>
```

The CLI outputs structured JSON designed for agent consumption. All commands return `success`, `action`, `result`, `next_steps`, and `hints` fields. Errors include `error` and `recovery_steps`.

**Reporting bugs:** when a command fails with an unexpected error (`provider_error`, `internal_error`, or a 5xx), or the user tells you something is broken, file a report with `naive report` (see "Reporting bugs & feedback" below). Do NOT report self-correctable errors — `insufficient_credits`, `unauthorized`/`forbidden`, `invalid_input`, `resource_not_found` — fix those directly.

## Quick Start

```bash
# 1. Register (creates account, returns API key)
naive register --name "My Agent" --email owner@example.com --password your-password

# 2. Export the key (or pass --api-key to each command)
export NAIVE_API_KEY=nv_sk_...

# 3. Check who you are
naive status

# 4. Start using primitives
naive search "latest AI news"
naive email send --from-inbox <inbox_id> --to user@example.com --subject "Hello" --body "Hi there"
naive images generate --model fal-ai/fast-sdxl "a sunset over mountains"
naive video generate --model fal-ai/minimax/video-01-live "ocean waves"
```

## Available CLI Commands

### Identity & Status
- `naive status` — Your agent profile, credits, limits
- `naive usage` — Recent usage history

### Reporting bugs & feedback
- `naive report "<what went wrong>" --command "<cmd>" --kind error` — File a bug report (e.g. a command failed with provider_error/internal_error/5xx, or produced a clearly-wrong result)
- `naive report "<request or gripe>" --kind feedback` — Send a feature request / feedback
- Optional flags: `--stack "<error or log excerpt>"`, `--session <id>`. Common secret shapes are scrubbed client-side (best-effort — don't paste secrets).
- Returns `{ accepted, reportId }` (HTTP 202) — receipt confirmation; the tracked issue is filed shortly after (reports are batched).

### Company
- `naive companies show` — View current company details (name, slug, description)
- `naive companies rename "<name>"` — Rename the current company
- `naive companies update --name "<name>" --description "<desc>"` — Update company details
- `naive companies` — List all accessible companies
- `naive companies select <id>` — Switch to a different company

### Domains
- `naive domains` — List all domains (system + custom). Response includes `app_connect_status`.
- `naive domains connect --domain example.com` — Connect a custom domain
- `naive domains setup-records <id>` — View the Resend email-provider setup records for verification (read-only; alias: `dns-records`)
- `naive domains verify <id>` — Trigger DNS verification
- `naive domains search <domain>` — Check domain availability and price
- `naive domains purchase <domain>` — Purchase a domain via Stripe checkout
- `naive domains zone-records <id>` — List every record on the live Vercel zone (with provider record IDs)
- `naive domains set-record <id> --type A --name @ --value 1.2.3.4` — Create or replace a record
- `naive domains delete-record <id> <record_id>` — Delete a record by provider record ID

Two DNS surfaces:
- `setup-records` (== GET /v1/domains/:id/dns-records, MCP `naive_resend_setup_records`): the Resend email-provider records the customer must add at their registrar to pass verification. Read-only.
- `zone-records` (== /v1/domains/:id/zone-records, MCP `naive_list_dns_records` / `naive_set_dns_record` / `naive_delete_dns_record`): every record currently on the live Vercel zone, with the provider record IDs needed for delete. Mutable.

DNS edit safety rules (enabled by default; flip AGENT_DNS_EDIT_ENABLED=false on the API to disable):
- System domains (registrar=system) are read-only.
- DMARC/DKIM and inbound MX/TXT records are protected (returns 403 PROTECTED_RECORD).
- Wildcard names ('*' or '*.foo') and CNAME at apex are rejected.
- CAA values must use an allowed CA (ssl.com, letsencrypt.org, digicert.com, sectigo.com, globalsign.com, amazon.com, pki.goog, google.com).
- Per-company rate limit: 5 mutations/min, 20/hr. The 429 response carries a Retry-After header.
- Records carry a `naive:owned;company=<id>` ownership comment (the legacy `paperclip:owned` prefix is also recognized for cross-product compatibility); overwriting an unowned record requires `acknowledge_unowned=true`.
- Apex A/AAAA writes atomically flip the domain to `app_connect_status = "agent_managed"` (with rollback on Vercel failure). Reapers/connect sweeps in either Naive product respect this state.
- If the response includes `mock: true`, the operation was simulated (no real Vercel write).
- Every successful or rejected DNS edit appends an `activity_log` row (`dns.record.set`, `dns.record.delete`, `dns.record.rejected`) and emits a `domain.updated` live event.

### Live events
- `GET /v1/events` — Server-Sent Events stream of company-scoped live events. Currently emitted: `domain.updated` (DNS edits + apex flips), `activity.logged` (every audit row).

### Apps (Web Applications)
Vercel-backed Next.js apps with optional Supabase database. Fully standalone — no orchestration required: create an app, clone the starter template from GitHub, build locally, and deploy by running `naive apps deploy` inside the project directory.
- `naive apps list` — List all apps
- `naive apps create --name "<name>" --type frontend_only|fullstack [--variant <variant>]` — Create app (provisions Vercel + optional Supabase; returns the template clone command)
- `naive apps templates` — List starter templates (GitHub repo + clone commands)
- `naive apps show <id>` — View app details including Vercel URL
- `naive apps deploy <id> [--dir <path>]` — Deploy: uploads your local project directory (direct mode), or deploys the agent workspace when run inside a container
- `naive apps publish <id> --deployment <deployment-id>` — Promote to production
- `naive apps deployments <id>` — Deployment history
- `naive apps retry <id>` — Retry failed provisioning
- `naive apps secrets list <id>` — List env var keys
- `naive apps secrets set <id> <KEY> <VALUE> --target preview|production` — Set env var (synced to Vercel)
- `naive apps secrets delete <id> <KEY> --target preview|production` — Delete env var (removed from Vercel)
- `naive apps secrets reveal <id> <KEY> --target preview|production` — Reveal env var value
- `naive apps domains list <id>` — List app domains
- `naive apps domains add <id> <domain>` — Add custom domain
- `naive apps domains remove <id> <domainId>` — Remove a domain
- `naive apps domains set-primary <id> <domainId>` — Set primary production domain
- `naive apps domains connect <id> <domainId>` — Connect company domain
- `naive apps domains disconnect <id> <domainId>` — Disconnect company domain
- `naive apps domains verify-dns <id> <domainId>` — Verify DNS
- `naive apps db tables <id>` — List database tables (fullstack only)
- `naive apps db query <id> "<sql>"` — Run SQL query (fullstack only)
- `naive apps vercel <id> <METHOD> <path> [--body '<json>']` — Call any Vercel REST API operation, scoped to the app's project (see https://vercel.com/docs/rest-api)
- `naive apps supabase <id> <METHOD> <path> [--body '<json>']` — Call any Supabase Management API operation, scoped to the app's project (see https://supabase.com/docs/reference/api)
- `naive apps delete <id>` — Delete app and all infrastructure

App types: `frontend_only` = Vercel only (landing pages, static); `fullstack` = Vercel + Supabase (SaaS, dashboards, apps with databases).

### Email
- `naive email inboxes` — List available inboxes
- `naive email create --local-part mybot` — Create a new inbox
- `naive email delete <id>` — Delete an inbox
- `naive email send --from-inbox <id> --to <addr> --subject <s> --body <b>` — Send email
- `naive email inbox` — List received emails
- `naive email read <id>` — Read a specific email

### Search
- `naive search "query"` — Web search
- `naive search url <url>` — Read and extract from a URL
- `naive search research "topic"` — Deep multi-source research (async)

### LLM (OpenRouter-backed chat completions — 300+ models)
- `naive llm chat -m <model> "prompt"` — Run a chat completion (e.g. -m anthropic/claude-sonnet-4.6)
- `naive llm chat -m <model> "prompt" --system "..." --fallback <m2> <m3>` — System prompt + fallback chain
- `naive llm models [search]` — List the models OpenRouter can route to (free)

A full wrapper over OpenRouter. The request/response bodies are OpenAI-compatible. Billed in credits by the model's token cost. Drop-in: point any OpenAI/OpenRouter SDK at `https://api.usenaive.ai/v1/proxy/openrouter` with your nv_sk_ key.

### Browser (cloud browser + autonomous signup/login)
- `naive browser session create` — Open a live cloud browser session (0 credits; time floor 1-3 billed at close)
- `naive browser navigate <id> <url>` — Navigate (1 credit)
- `naive browser act <id> "<instruction>"` — Natural-language action: click/fill/scroll (1 credit)
- `naive browser extract <id> "<instruction>"` — Extract structured data (1 credit)
- `naive browser observe <id> "<instruction>"` — List candidate elements (1 credit)
- `naive browser screenshot <id>` — Capture the page (1 credit)
- `naive browser signup <service> <url>` — Autonomous account creation + credential vaulting (4 credits, approval-gated)
- `naive browser login <service> <url>` — Autonomous re-login from the vaulted credential (3 credits)
- `naive browser session close <id>` — Close the session

Point the user's profile email at a provisioned inbox before signup so verification mail is received.

### Images
- `naive images generate --model <model> "prompt"` — Generate images (async)
- `naive images stock "query"` — Search stock photos
- `naive images models` — List available models

### Video
- `naive video generate --model <model> "prompt"` — Generate video (async)
- `naive video models` — List available models

### Identity Verification (KYC)
- `naive verification start --members '<json>'` — Start KYC for company members
- `naive verification list` — List all verification requests
- `naive verification status <id>` — Get verification + member statuses
- `naive verification complete <memberId> --token <token>` — Submit validation token
- `naive verification resend <memberId>` — Resend a member's KYC link

### Company Formation (LLC via Doola — $249 fee)
Two-step flow: submit creates a Stripe Checkout for $249, then execute submits to Doola after payment.
- `naive formation naics-codes` — List NAICS industry codes
- `naive formation submit --verification-id <id> --state WY --naics <id> --description "..." --names '<json>'` — Step 1: Create $249 Stripe Checkout (returns checkout_url)
- `naive formation retry-payment <formationId>` — Regenerate checkout URL if the original expired
- `naive formation execute <formationId>` — Step 2: Submit to Doola after user has paid
- `naive formation list` — List all formations
- `naive formation status <id>` — Get formation details
- `naive formation documents <id>` — List formation documents
- `naive formation download <formationId> <docId>` — Get document download URL

If a formation fails after payment is confirmed, contact support@usenaive.ai (do NOT create a duplicate formation — the $249 is held against the original).

### Social Media
- `naive social status` — Check activation + connected accounts
- `naive social activate` — Activate social media integration
- `naive social connect --platform twitter --redirect-url <url>` — Get OAuth URL for a platform
- `naive social portal --redirect-url <url>` — Multi-platform connect portal URL
- `naive social accounts` — List connected accounts
- `naive social disconnect <id>` — Disconnect an account
- `naive social sync` — Sync connected accounts
- `naive social post "content" --platforms twitter,linkedin --publish` — Create + publish a post (1 credit)
- `naive social post "content" --platforms twitter,linkedin` — Create a draft (free)
- `naive social post "content" --platforms youtube --media-url <url> --youtube-type SHORT` — Post with video
- `naive social posts` — List posts
- `naive social get <id>` — Get post details
- `naive social publish <id>` — Publish a draft (1 credit)
- `naive social analytics <id>` — Post analytics
- `naive social comments <id>` — Post comments
- `naive social edit <id>` — Edit a draft post
- `naive social delete <id>` — Delete a post
- `naive social label <id> --label <label>` — Set a label on an account
- `naive social upload --url <url>` — Upload media from URL
- `naive social account-analytics <id>` — Account-level analytics

Platform tips:
- YouTube: --youtube-type SHORT (vertical, <3min, default) or VIDEO (landscape)
- TikTok: privacy auto-set to PUBLIC_TO_EVERYONE, requires video
- Instagram: defaults to Reel type for video posts
- Twitter: content auto-truncated to 280 chars
- Reddit: pass --platform-data '{"REDDIT":{"sr":"subreddit"}}' for subreddit targeting
- Bluesky: content auto-truncated to 300 chars

### Virtual Cards
- `naive cards` — List all virtual cards
- `naive cards cardholder` — View cardholder details
- `naive cards create-cardholder --first-name "..." --last-name "..." ...` — Create Stripe Issuing cardholder
- `naive cards create --name "..." --spending-limit 5000` — Create card (returns checkout URL)
- `naive cards details <id>` — Get card credentials (PAN/CVC or redeem code)
- `naive cards check-payment <id>` — Check if card funding checkout completed
- `naive cards top-up <id> --amount 2500` — Top up card spending limit (returns checkout URL)
- `naive cards cancel <id>` — Cancel a card
- `naive cards assign <id> --agent-id <uuid>` — Assign agent to card
- `naive cards unassign <id> <agent_id>` — Remove agent assignment
- `naive cards log-transaction <id> --amount 1500 --description "..."` — Log a spend
- `naive cards transactions` — List card transactions

### Phone (numbers, SMS, and LiveKit voice)
- `naive phone provision --ein 12-3456789 --area-code 415` — Buy a US number + register the 10DLC carrier campaign (EIN required)
- `naive phone list` — List phone numbers
- `naive phone status` — Show the carrier-registration pipeline (account → campaign → numbers)
- `naive phone send --from <phone_id> --to +14155551234 --body "Hi"` — Send an outbound SMS (carrier-gated until campaign approved)
- `naive phone voice-enable <phone_id>` — Enable Surge SIP + LiveKit voice for a number
- `naive phone call --from <phone_id> --to +14155551234` — Place an outbound voice call (approval-gated)
- `naive phone calls <phone_id>` — List recent voice calls
- `naive phone hangup <call_id>` — End a live voice call
- `naive phone messages <phone_id>` — List received SMS (newest first)
- `naive phone read <message_id>` — Read a received SMS in full
- `naive phone assign <phone_id> --agent-id <uuid>` — Connect an agent to a number
- `naive phone release <phone_id>` — Release a number back to the provider (stops billing)
Note: inbound SMS works immediately; outbound SMS unlocks automatically when the carrier campaign is approved (~1-2 business days). Provisioning requires a completed LLC formation + EIN.

### Mobile (cloud emulators/devices via Mobilerun)
- `naive mobile provision --country US` — Create a cloud phone, billed per minute from your credits (provisions immediately; the meter runs until you terminate — no auto-stop) (SENSITIVE)
- `naive mobile devices` — List your phones/devices with live state
- `naive mobile status` — Show whether Mobile is configured/reachable + your active/pending phone counts
- `naive mobile wait <device_id>` — Block until a device is ready
- `naive mobile stream <device_id>` — Get a signed live-stream URL for the device screen
- `naive mobile run "Open Settings and enable dark mode" --device <device_id> --vision` — Run a natural-language agent task on a device (SENSITIVE)
- `naive mobile task <task_id>` / `naive mobile screenshots <task_id>` — Poll task status / list step screenshots
- `naive mobile search "screenshot"` — Discover any Mobilerun operationId (wildcard)
- `naive mobile call <operationId> --path deviceId=<id>` — Call any Mobilerun operation, scoped to your own devices/tasks (SENSITIVE if mutating)
- `naive mobile proxy-set <device_id> --host <h> --port <p>` — Attach a SOCKS5 proxy (residential IP; datacenter by default) (SENSITIVE)
- `naive mobile terminate <device_id>` — Release a device and STOP its per-minute meter (SENSITIVE)
Note: Naïve holds the Mobilerun operator key — your agents never see it. Every device/task is scoped to your tenant.

### Trading (brokerage via OAuth — stocks, options, crypto)
- `naive trading connect --env paper` — Start the brokerage OAuth flow (returns an authorize URL)
- `naive trading connections` — List connected environments (paper/live)
- `naive trading account` — Show the connected brokerage account
- `naive trading assets --asset-class crypto` — List tradable assets
- `naive trading order --symbol BTC/USD --notional 25 --side buy --type market --tif gtc` — Place an order (SENSITIVE)
- `naive trading positions` — List open positions
- `naive trading close <symbol>` — Close/liquidate a position (SENSITIVE)
- `naive trading orders --status open` — List orders
- `naive trading cancel <id>` — Cancel an open order (SENSITIVE)
- `naive trading quote --symbols BTC/USD,ETH/USD` — Latest quote(s)

### Jobs (for async operations)
- `naive jobs` — List your async jobs
- `naive jobs get <id>` — Get job status and result
- `naive jobs cancel <id>` — Cancel a running job

### SEO
- `naive seo keywords google search-volume --keywords "ai tools"` — Google search volume, CPC, competition
- `naive seo keywords bing search-volume --keywords "ai tools"` — Bing search volume
- `naive seo keywords google-trends explore --keywords "ai tools"` — Google Trends data
- `naive seo backlinks summary --target example.com` — Backlink profile summary
- `naive seo backlinks competitors --target example.com` — Backlink competitors
- `naive seo labs google keyword-overview --keywords "ai tools"` — Keyword overview with SERP data
- `naive seo labs google ranked-keywords --target example.com` — Keywords a domain ranks for
- `naive seo labs google serp-competitors --keywords "ai tools"` — SERP competitors for keywords

### Mobile App Data
- `naive app-data google app-searches --keyword "fitness"` — Search Google Play for apps
- `naive app-data google app-info --app-id com.example.app` — Get detailed app info
- `naive app-data google app-reviews --app-id com.example.app` — Get app reviews
- `naive app-data apple app-searches --keyword "fitness"` — Search App Store
- `naive app-data apple app-listings --title "fitness"` — Browse App Store listings

### Business Data
- `naive business google my-business-info --keyword "pizza nyc"` — Google Business Profile data
- `naive business google hotel-searches --keyword "hotels paris"` — Google Hotels search
- `naive business google reviews --keyword "starbucks"` — Google Reviews
- `naive business trustpilot search --keyword "hosting"` — Search Trustpilot
- `naive business trustpilot reviews --domain example.com` — Trustpilot reviews
- `naive business tripadvisor search --keyword "pizza"` — Search TripAdvisor
- `naive business social facebook --targets "https://example.com"` — Facebook engagement data

### AEO/GEO — AI Optimization
- `naive aeo llm-responses chatgpt --keyword "best CRM"` — Get ChatGPT's response to a query
- `naive aeo llm-responses claude --keyword "best CRM"` — Get Claude's response
- `naive aeo llm-responses gemini --keyword "best CRM"` — Get Gemini's response
- `naive aeo llm-scraper --keyword "best CRM"` — Scrape ChatGPT Search results
- `naive aeo ai-keywords --keywords "ai tools"` — AI keyword search volume
- `naive aeo llm-mentions search --keyword "brand"` — Track brand mentions in LLMs
- `naive aeo llm-mentions top-domains --keyword "ai tools"` — Top mentioned domains

**REST callers note:** The CLI maps `--keyword` to `user_prompt` for LLM Responses and defaults `model_name` to `gpt-4o-mini`. When calling the REST API directly, use `{ "user_prompt": "...", "model_name": "gpt-4o-mini" }` instead of `{ "keyword": "..." }`. For LLM Mentions, use `domain` (or `keyword`) plus `target` as an array of objects (e.g. `[{"domain": "example.com"}]`).

### E-commerce Data
- `naive ecommerce google products --keyword "laptop"` — Google Shopping product listings
- `naive ecommerce google product-info --product-id "123"` — Product details from Google Shopping
- `naive ecommerce google sellers --product-id "123"` — Product sellers and prices
- `naive ecommerce google reviews --product-id "123"` — Product reviews
- `naive ecommerce amazon products --keyword "headphones"` — Amazon product search
- `naive ecommerce amazon asin --asin "B08N5WRWNW"` — Amazon ASIN info
- `naive ecommerce amazon sellers --asin "B08N5WRWNW"` — Amazon sellers

### Apps — Web Application Deployment
- `naive apps list` — List all web apps
- `naive apps create --name "My App" --type frontend_only` — Create a new app (type: frontend_only or fullstack)
- `naive apps show <id>` — Full app details (Vercel, Supabase, secrets, domains, deployments)
- `naive apps delete <id>` — Delete app and all infrastructure
- `naive apps deploy <id>` — Trigger a preview deployment
- `naive apps publish <id> --deployment <deploymentId>` — Promote a deployment to production
- `naive apps deployments <id>` — List deployment history
- `naive apps secrets list <id>` — List env variable keys
- `naive apps secrets set <id> KEY VALUE --target preview|production` — Set an env variable
- `naive apps secrets delete <id> KEY --target preview|production` — Delete an env variable
- `naive apps secrets reveal <id> KEY --target preview|production` — Show env variable value
- `naive apps domains list <id>` — List domains attached to app
- `naive apps domains add <id> <domain>` — Add a custom domain
- `naive apps domains remove <id> <domainId>` — Remove a domain
- `naive apps domains connect <id> <companyDomainId>` — Connect a company domain as production domain
- `naive apps domains disconnect <id> <companyDomainId>` — Disconnect a company domain
- `naive apps domains verify-dns <id> <companyDomainId>` — Verify DNS propagation

Each app is backed by Vercel (all types) + Supabase (fullstack type). A dedicated engineer agent is provisioned on creation. The engineer can build/deploy autonomously via the kanban task system.

## AgentProfiles & multi-tenancy (v2)

The unit of isolation is a **governed agent profile per tenant**. Each tenant gets its
own isolated data plane (identity, card, comms, vault, connections) governed by an
AccountKit policy. Provision an agent profile and pull its governed tools:

- `POST /v1/users/:user_id/agent-profiles` — provision (idempotent on `idempotency_key`); body `{ template, idempotency_key, overrides }`
- `GET /v1/agent-profiles/:id` — agent profile status
- `POST /v1/agent-profiles/:id/revoke` — absolute revoke (suspends the agent profile; the gateway denies further tool calls)
- `POST /v1/runtime/:pool/start` — hosted runtime (optional; BYO-runtime is the lead path — run the agent on your own infra and pull `agentProfile.tools()`)

SDK: `@usenaive-sdk/server` (`forUser(id).provision(template)`, `agentProfile.tools()`,
`agentProfile.revoke()`), `@usenaive-sdk/iac` (declarative `naive.config.ts`),
`@usenaive-sdk/runtime` (`agentProfile.tools()` inside a hosted agent).

Per-tenant primitives are mounted under `/v1/users/:user_id/...` (use `default` for the api key's default user).

- `naive users` — Create/list/update/suspend tenant users (control plane)
- `naive account-kits` — Policy templates that enable/disable primitives + connections per user
- `naive connections` — Connect 3rd-party apps (OAuth/API key) via Composio, gated by the kit
- `naive vault` — Encrypted per-user credential store (put/get/list/rotate/delete)
- `naive approvals` — Human-in-the-loop queue; sensitive agent actions land here as `pending` until approved
- `naive logs` — Per-user activity audit trail

Sessions (`POST /v1/users/:id/sessions`) mint a TTL-limited `nv_sess_` token + scoped MCP URL so an agent acts as exactly one user. AccountKits, tenant Users, Approvals, and Sessions are control-plane and REST/CLI-only (no MCP tools).

## MCP Fallback

If the CLI cannot be installed (e.g. sandboxed environment), connect via MCP:

```
SSE URL: https://api.usenaive.ai/mcp/sse
Header: Authorization: Bearer nv_sk_...
```

Most primitives are available as MCP tools (prefixed with `naive_`). Exceptions are REST/CLI-only: orchestration (CEO, tasks, objectives, employees, cron, memory), AccountKits, tenant Users management, Approvals (approve/deny), Sessions, Templates, the `profile` primitive, and registration/login/company-selection.

## REST API Reference (last resort)

Base URL: `https://api.usenaive.ai`
Auth: `Authorization: Bearer nv_sk_...`

| Category | Endpoints |
| -------- | --------- |
| Identity | `GET /v1/identity`, `GET /v1/identity/resources` |
| AgentProfiles | `POST /v1/users/:user_id/agent-profiles` (provision), `GET /v1/agent-profiles`, `GET /v1/agent-profiles/:id`, `POST /v1/agent-profiles/:id/revoke`, `POST /v1/runtime/:pool/start` |
| Domains  | `GET /v1/domains`, `POST /v1/domains/connect`, `GET /v1/domains/:id/dns-records` (Resend setup records), `POST /v1/domains/:id/verify`, `GET /v1/domains/search`, `POST /v1/domains/purchase`, `GET /v1/domains/:id/zone-records` (live Vercel zone), `POST /v1/domains/:id/zone-records`, `DELETE /v1/domains/:id/zone-records/:recordId` |
| Events   | `GET /v1/events` (SSE stream) |
| Billing  | `GET /v1/billing/plans`, `POST /v1/billing/subscribe`, `POST /v1/billing/upgrade`, `GET /v1/billing/subscription`, `POST /v1/billing/portal`, `GET /v1/billing/packs`, `POST /v1/billing/topup` |
| Email    | `GET /v1/email/inboxes`, `POST /v1/email/inboxes`, `DELETE /v1/email/inboxes/:id`, `POST /v1/email/send`, `GET /v1/email/inbox`, `GET /v1/email/:id` |
| Search   | `POST /v1/search`, `POST /v1/search/url`, `POST /v1/search/research` |
| LLM      | `POST /v1/llm/chat/completions` (OpenAI-compatible, streaming), `GET /v1/llm/models`, `GET /v1/llm/generation`; drop-in proxy `POST /v1/proxy/openrouter/*` |
| Images   | `POST /v1/images/generate`, `GET /v1/images/stock`, `GET /v1/images/models`, `GET /v1/images/pricing` |
| Video    | `POST /v1/video/generate`, `GET /v1/video/models`, `GET /v1/video/pricing` |
| Social   | `GET /v1/social/status`, `POST /v1/social/activate`, `POST /v1/social/connect`, `POST /v1/social/portal`, `GET /v1/social/accounts`, `POST /v1/social/posts`, `POST /v1/social/posts/:id/publish` |
| Verification | `POST /v1/verification`, `GET /v1/verification`, `GET /v1/verification/:id`, `POST /v1/verification/members/:id/complete`, `POST /v1/verification/members/:id/resend` |
| Formation | `GET /v1/formation/naics-codes`, `POST /v1/formation` (creates $249 checkout), `POST /v1/formation/:id/retry-payment` (regenerate checkout), `POST /v1/formation/:id/submit` (after payment), `GET /v1/formation`, `GET /v1/formation/:id`, `GET /v1/formation/:id/documents`, `GET /v1/formation/:id/documents/:docId` |
| Apps     | `GET /v1/apps`, `POST /v1/apps`, `GET /v1/apps/:id`, `DELETE /v1/apps/:id`, `POST /v1/apps/:id/deploy`, `POST /v1/apps/:id/publish`, `GET /v1/apps/:id/deployments`, `GET /v1/apps/:id/secrets`, `POST /v1/apps/:id/secrets`, `DELETE /v1/apps/:id/secrets/:key`, `GET /v1/apps/:id/secrets/:key/reveal`, `GET /v1/apps/:id/domains`, `POST /v1/apps/:id/domains`, `DELETE /v1/apps/:id/domains/:domainId`, `POST /v1/apps/:id/connect-domain`, `DELETE /v1/apps/:id/connect-domain/:domainId`, `POST /v1/apps/:id/verify-domain-dns` |
| Jobs     | `GET /v1/jobs`, `GET /v1/jobs/:id`, `DELETE /v1/jobs/:id` |
| SEO       | `POST /v1/seo/keywords/google/search-volume`, `POST /v1/seo/backlinks/summary`, `POST /v1/seo/labs/google/keyword-overview`, + ~100 more |
| App Data  | `POST /v1/app-data/google/app-searches`, `POST /v1/app-data/apple/app-searches`, + ~30 more |
| Business  | `POST /v1/business/google/my-business-info`, `POST /v1/business/trustpilot/search/task`, + ~35 more |
| AEO/GEO   | `POST /v1/aeo/llm-responses/chatgpt`, `POST /v1/aeo/llm-mentions/search`, + ~25 more |
| E-commerce | `POST /v1/ecommerce/google/products/task`, `POST /v1/ecommerce/amazon/products/task`, + ~30 more |
| Cards    | `GET /v1/cards`, `POST /v1/cards`, `GET /v1/cards/:id/details`, `POST /v1/cards/:id/top-up`, `DELETE /v1/cards/:id`, + 11 more |
| Phone    | `POST /v1/phone/provision`, `GET /v1/phone`, `GET /v1/phone/status`, `POST /v1/phone/:id/sms`, `POST /v1/phone/:id/voice/enable`, `POST /v1/phone/:id/calls`, `GET /v1/phone/:id/calls`, `DELETE /v1/phone/calls/:id`, `GET /v1/phone/:id/messages`, `GET /v1/phone/messages/:id`, `POST /v1/phone/:id/assign`, `DELETE /v1/phone/:id` |
| Mobile   | `POST /v1/mobile/devices`, `GET /v1/mobile/devices`, `GET /v1/mobile/status`, `GET /v1/mobile/devices/:id/stream`, `POST /v1/mobile/devices/:id/wait`, `POST /v1/mobile/tasks`, `GET /v1/mobile/tasks/:id`, `GET /v1/mobile/methods`, `POST /v1/mobile/call`, `DELETE /v1/mobile/devices/:id` |
| Trading  | `POST /v1/trading/connect`, `GET /v1/trading/account`, `GET /v1/trading/positions`, `POST /v1/trading/orders`, `DELETE /v1/trading/orders/:id`, + 8 more |
| Status   | `GET /v1/status`, `GET /v1/usage` |

### Billing
- `naive billing plans` — List subscription plans ($49/mo Starter, $149/mo Pro)
- `naive billing subscribe --plan <plan>` — Subscribe (returns checkout URL)
- `naive billing upgrade --plan <plan>` — Upgrade existing subscription
- `naive billing status` — Check subscription + credit balance
- `naive billing portal` — Get billing management URL
- `naive billing packs` — List credit top-up packs ($10-$100)
- `naive billing topup --pack <id>` — Buy credits (returns checkout URL)

## Notes

- A system domain ({slug}.usenaive.ai) is auto-provisioned on registration (may be `pending_dns` until DNS verifies). Use `naive domains` to check, `naive domains verify <id>` to trigger.
- Image and video generation are async — they return a job ID. Poll with `naive jobs status <id>`.
- Pricing is dynamic (based on real-time model costs). Always check pricing before generating.
- Credits never expire. If you run out, use `naive billing topup` to buy more.
- New accounts start with 20 free credits; buy more with `naive billing topup` or by subscribing to a plan.
- SEO, App Data, Business Data, AEO, and E-commerce primitives are pay-per-use via our data provider (configured server-side).