# Naive API v2

> Standalone Agentic API — email, search, image generation, video generation, social media, identity verification, and async jobs for autonomous AI agents.

## Docs

- [AEO API Reference](https://usenaive.ai/docs/api-reference/aeo/overview.md): All AEO/GEO REST endpoints — LLM Responses, Scraper, AI Keywords, and LLM Mentions.
- [App Data API Reference](https://usenaive.ai/docs/api-reference/app-data/overview.md): All App Data REST endpoints — Google Play and App Store.
- [List Companies](https://usenaive.ai/docs/api-reference/auth/companies.md): GET /v1/auth/companies — List companies available to the authenticated agent.
- [API Keys](https://usenaive.ai/docs/api-reference/auth/keys.md): Create, list, and revoke API keys.
- [Link Account](https://usenaive.ai/docs/api-reference/auth/link.md): POST /v1/auth/link — Link to an existing Naive account by email verification.
- [Login](https://usenaive.ai/docs/api-reference/auth/login.md): POST /v1/auth/login — Authenticate with email and password to get a fresh API key.
- [Who Am I](https://usenaive.ai/docs/api-reference/auth/me.md): GET /v1/auth/me — Get current auth context (agent + company).
- [Register](https://usenaive.ai/docs/api-reference/auth/register.md): POST /v1/auth/register — Create a new Naive account with email and password, get an API key immediately.
- [Select Company](https://usenaive.ai/docs/api-reference/auth/select-company.md): POST /v1/auth/select-company — Switch active company context.
- [Verify Code](https://usenaive.ai/docs/api-reference/auth/verify.md): POST /v1/auth/verify — Complete account linking with the verification code.
- [Credit Packs](https://usenaive.ai/docs/api-reference/billing/packs.md): List available credit top-up packs with prices
- [List Plans](https://usenaive.ai/docs/api-reference/billing/plans.md): List available subscription plans with pricing and trial eligibility
- [Billing Portal](https://usenaive.ai/docs/api-reference/billing/portal.md): Get a billing portal URL for subscription management
- [Subscribe](https://usenaive.ai/docs/api-reference/billing/subscribe.md): Create a subscription checkout session
- [Subscription Status](https://usenaive.ai/docs/api-reference/billing/subscription.md): Check current subscription status and credit balance
- [Buy Credits](https://usenaive.ai/docs/api-reference/billing/topup.md): Purchase a credit pack via checkout
- [Upgrade Plan](https://usenaive.ai/docs/api-reference/billing/upgrade.md): Upgrade to a higher subscription plan
- [Business Data API Reference](https://usenaive.ai/docs/api-reference/business-data/overview.md): All Business Data REST endpoints — Google, Trustpilot, TripAdvisor, and Social Media.
- [Assign Agent](https://usenaive.ai/docs/api-reference/cards/assign.md): Assign an agent to a card
- [List Assignments](https://usenaive.ai/docs/api-reference/cards/assignments.md): List all agents assigned to a card
- [Cancel Card](https://usenaive.ai/docs/api-reference/cards/cancel.md): Cancel and deactivate a virtual card
- [Get Cardholder](https://usenaive.ai/docs/api-reference/cards/cardholder.md): Get the company's Stripe Issuing cardholder
- [Check Payment](https://usenaive.ai/docs/api-reference/cards/check-payment.md): Check the checkout payment status for a card
- [Create Card](https://usenaive.ai/docs/api-reference/cards/create.md): Create a virtual card and Stripe Checkout session
- [Create Cardholder](https://usenaive.ai/docs/api-reference/cards/create-cardholder.md): Create a Stripe Issuing cardholder for the company
- [Get Card Details](https://usenaive.ai/docs/api-reference/cards/details.md): Get card credentials (number, CVC, expiry)
- [List Cards](https://usenaive.ai/docs/api-reference/cards/list.md): List all virtual cards for the company
- [Log Transaction](https://usenaive.ai/docs/api-reference/cards/log-transaction.md): Manually log a transaction against a card
- [Refund Card](https://usenaive.ai/docs/api-reference/cards/refund.md): Refund a card that failed issuance or payment
- [Retry Issuance](https://usenaive.ai/docs/api-reference/cards/retry-issue.md): Retry card issuance after a failed attempt
- [Top Up Card](https://usenaive.ai/docs/api-reference/cards/top-up.md): Add funds to an existing card via checkout
- [List Transactions](https://usenaive.ai/docs/api-reference/cards/transactions.md): List card transactions across all cards
- [Unassign Agent](https://usenaive.ai/docs/api-reference/cards/unassign.md): Remove an agent's assignment from a card
- [Update Cardholder](https://usenaive.ai/docs/api-reference/cards/update-cardholder.md): Update the company's Stripe Issuing cardholder
- [Connect Domain](https://usenaive.ai/docs/api-reference/domains/connect.md): POST /v1/domains/connect — Connect your own domain (BYOD) for email sending.
- [Resend Setup Records](https://usenaive.ai/docs/api-reference/domains/dns-records.md): GET /v1/domains/:id/dns-records — View the Resend email-provider setup records the customer must add at their registrar to pass domain verification. Read-only.
- [List Domains](https://usenaive.ai/docs/api-reference/domains/list.md): GET /v1/domains — List all domains for your company.
- [Purchase Domain](https://usenaive.ai/docs/api-reference/domains/purchase.md): Purchase a domain via checkout
- [Search Domain](https://usenaive.ai/docs/api-reference/domains/search.md): Check if a domain is available for purchase
- [Verify Domain](https://usenaive.ai/docs/api-reference/domains/verify.md): POST /v1/domains/:id/verify — Trigger DNS verification for a domain.
- [Delete Zone Record](https://usenaive.ai/docs/api-reference/domains/zone-records-delete.md): DELETE /v1/domains/:id/zone-records/:recordId — Remove a DNS record from the live Vercel zone.
- [List Zone Records](https://usenaive.ai/docs/api-reference/domains/zone-records-list.md): GET /v1/domains/:id/zone-records — List every DNS record on the live Vercel zone, including provider record IDs.
- [E-commerce API Reference](https://usenaive.ai/docs/api-reference/ecommerce/overview.md): All E-commerce REST endpoints — Google Shopping and Amazon.
- [Create Inbox](https://usenaive.ai/docs/api-reference/email/create-inbox.md): POST /v1/email/inboxes — Create a new email inbox on your company's domain.
- [Delete Inbox](https://usenaive.ai/docs/api-reference/email/delete-inbox.md): DELETE /v1/email/inboxes/:id — Deactivate an email inbox (soft delete).
- [Get Email](https://usenaive.ai/docs/api-reference/email/get.md): GET /v1/email/:id — Get full email body by ID.
- [List Received Emails](https://usenaive.ai/docs/api-reference/email/inbox.md): GET /v1/email/inbox — List received emails, optionally filtered by inbox.
- [List Inboxes](https://usenaive.ai/docs/api-reference/email/inboxes.md): GET /v1/email/inboxes — List email addresses this agent can send from.
- [Send Email](https://usenaive.ai/docs/api-reference/email/send.md): POST /v1/email/send — Send an email from a specific inbox.
- [List Formation Documents](https://usenaive.ai/docs/api-reference/formation/documents.md): GET /v1/formation/:id/documents — List documents for a company formation.
- [Download Formation Document](https://usenaive.ai/docs/api-reference/formation/download.md): GET /v1/formation/:id/documents/:documentId — Get a temporary signed download URL.
- [Execute Formation](https://usenaive.ai/docs/api-reference/formation/execute.md): POST /v1/formation/:id/submit — Step 2: Submit formation to Doola after payment is complete.
- [Get Formation](https://usenaive.ai/docs/api-reference/formation/get.md): GET /v1/formation/:id — Get formation details, status, and documents.
- [List Formations](https://usenaive.ai/docs/api-reference/formation/list.md): GET /v1/formation — List all company formation requests.
- [List NAICS Codes](https://usenaive.ai/docs/api-reference/formation/naics-codes.md): GET /v1/formation/naics-codes — List available NAICS industry codes for formation.
- [Retry Formation Payment](https://usenaive.ai/docs/api-reference/formation/retry-payment.md): POST /v1/formation/:id/retry-payment — Generate a fresh Stripe Checkout URL for a formation whose checkout session expired.
- [Submit Formation](https://usenaive.ai/docs/api-reference/formation/submit.md): POST /v1/formation — Step 1: Validate KYC and create a $249 Stripe Checkout session for the formation fee.
- [List Emails](https://usenaive.ai/docs/api-reference/identity/emails.md): GET /v1/identity/emails — List available email inboxes.
- [Identity](https://usenaive.ai/docs/api-reference/identity/overview.md): GET /v1/identity — Full identity summary for the authenticated agent.
- [List Resources](https://usenaive.ai/docs/api-reference/identity/resources.md): GET /v1/identity/resources — All provisioned resources across categories.
- [Generate Images](https://usenaive.ai/docs/api-reference/images/generate.md): POST /v1/images/generate — Submit an image generation job.
- [Image Models](https://usenaive.ai/docs/api-reference/images/models.md): GET /v1/images/models — List available image generation models.
- [Image Status](https://usenaive.ai/docs/api-reference/images/status.md): GET /v1/images/:jobId — Check image generation job status.
- [Stock Photos](https://usenaive.ai/docs/api-reference/images/stock.md): GET /v1/images/stock — Search stock photos (free).
- [Cancel Job](https://usenaive.ai/docs/api-reference/jobs/cancel.md): DELETE /v1/jobs/:id — Cancel a queued or processing job.
- [Get Job](https://usenaive.ai/docs/api-reference/jobs/get.md): GET /v1/jobs/:id — Get details for a specific job.
- [List Jobs](https://usenaive.ai/docs/api-reference/jobs/list.md): GET /v1/jobs — List async jobs for the current agent.
- [API Overview](https://usenaive.ai/docs/api-reference/overview.md): Base URL, authentication, and endpoint conventions for the Naive API v2.
- [Read URL](https://usenaive.ai/docs/api-reference/search/read-url.md): POST /v1/search/url — Fetch and extract content from a URL.
- [Deep Research](https://usenaive.ai/docs/api-reference/search/research.md): POST /v1/search/research — Multi-source research with AI synthesis.
- [Web Search](https://usenaive.ai/docs/api-reference/search/web-search.md): POST /v1/search — Search the web for information.
- [SEO API Reference](https://usenaive.ai/docs/api-reference/seo/overview.md): All SEO REST endpoints — Keywords Data, Backlinks, and SEO Labs.
- [Account Analytics](https://usenaive.ai/docs/api-reference/social/account-analytics.md): GET /v1/social/accounts/:id/analytics — Get analytics for a connected social account.
- [List Accounts](https://usenaive.ai/docs/api-reference/social/accounts.md): GET /v1/social/accounts — List all connected social accounts.
- [Activate Social](https://usenaive.ai/docs/api-reference/social/activate.md): POST /v1/social/activate — Activate social posting for your team.
- [Connect Account](https://usenaive.ai/docs/api-reference/social/connect.md): POST /v1/social/connect — Get an OAuth URL to connect a social account.
- [Create Post](https://usenaive.ai/docs/api-reference/social/create-post.md): POST /v1/social/posts — Create a social post as a draft, or publish/schedule it immediately.
- [Delete Post](https://usenaive.ai/docs/api-reference/social/delete-post.md): DELETE /v1/social/posts/:id — Delete a social post.
- [Disconnect Account](https://usenaive.ai/docs/api-reference/social/disconnect.md): DELETE /v1/social/accounts/:id — Disconnect a social account.
- [Edit Post](https://usenaive.ai/docs/api-reference/social/edit-post.md): PATCH /v1/social/posts/:id — Update a draft social post.
- [Get Post](https://usenaive.ai/docs/api-reference/social/get-post.md): GET /v1/social/posts/:id — Retrieve a single social post by ID.
- [Label Account](https://usenaive.ai/docs/api-reference/social/label.md): POST /v1/social/accounts/:id/label — Set a custom label on a social account.
- [List Posts](https://usenaive.ai/docs/api-reference/social/list-posts.md): GET /v1/social/posts — List social posts with optional filtering and pagination.
- [Social Portal](https://usenaive.ai/docs/api-reference/social/portal.md): POST /v1/social/portal — Get a hosted portal URL for managing social connections.
- [Post Analytics](https://usenaive.ai/docs/api-reference/social/post-analytics.md): GET /v1/social/posts/:id/analytics — Get analytics for a published post.
- [Post Comments](https://usenaive.ai/docs/api-reference/social/post-comments.md): GET /v1/social/posts/:id/comments — Get comments on a published post.
- [Publish Post](https://usenaive.ai/docs/api-reference/social/publish-post.md): POST /v1/social/posts/:id/publish — Publish a draft social post.
- [Social Status](https://usenaive.ai/docs/api-reference/social/status.md): GET /v1/social/status — Check whether social posting is activated and list connected accounts.
- [Sync Accounts](https://usenaive.ai/docs/api-reference/social/sync.md): POST /v1/social/sync — Sync all connected social accounts with the upstream provider.
- [Upload Media](https://usenaive.ai/docs/api-reference/social/upload.md): POST /v1/social/upload — Upload media for use in social posts.
- [Status](https://usenaive.ai/docs/api-reference/status/status.md): GET /v1/status — Agent status, credits, and resource summary.
- [Usage](https://usenaive.ai/docs/api-reference/status/usage.md): GET /v1/usage — Credit usage history.
- [Complete Member Verification](https://usenaive.ai/docs/api-reference/verification/complete.md): POST /v1/verification/members/:memberId/complete — Submit a Footprint validation token to confirm a member's KYC.
- [Get Verification](https://usenaive.ai/docs/api-reference/verification/get.md): GET /v1/verification/:id — Get a single verification with all member statuses.
- [List Verifications](https://usenaive.ai/docs/api-reference/verification/list.md): GET /v1/verification — List all identity verification requests for the company.
- [Resend Verification Link](https://usenaive.ai/docs/api-reference/verification/resend.md): POST /v1/verification/members/:memberId/resend — Regenerate and resend a KYC link for a member.
- [Start Verification](https://usenaive.ai/docs/api-reference/verification/start.md): POST /v1/verification — Start identity verification (KYC) for a set of company members.
- [Generate Video](https://usenaive.ai/docs/api-reference/video/generate.md): POST /v1/video/generate — Submit a video generation job.
- [Video Models](https://usenaive.ai/docs/api-reference/video/models.md): GET /v1/video/models — List available video generation models.
- [Video Status](https://usenaive.ai/docs/api-reference/video/status.md): GET /v1/video/:jobId — Check video generation job status.
- [aeo](https://usenaive.ai/docs/cli/aeo.md): AI search optimization — LLM responses, mentions tracking, and AI keyword data via the CLI.
- [app-data](https://usenaive.ai/docs/cli/app-data.md): App rankings, reviews, and metadata from Google Play and App Store via the CLI.
- [Billing](https://usenaive.ai/docs/cli/billing.md): Manage subscriptions, plans, and credit top-ups from the CLI
- [Cards](https://usenaive.ai/docs/cli/cards.md): Manage virtual cards — create, fund, assign, and track transactions from the CLI
- [domains](https://usenaive.ai/docs/cli/domains.md): Manage email domains — list, connect, verify, search, purchase, and edit DNS records on the live zone.
- [ecommerce](https://usenaive.ai/docs/cli/ecommerce.md): Product listings, pricing, sellers, and reviews from Google Shopping and Amazon via the CLI.
- [email](https://usenaive.ai/docs/cli/email.md): Send and manage emails using provisioned inboxes — identity-aware with structured agent output.
- [Formation](https://usenaive.ai/docs/cli/formation.md): Company formation (LLC incorporation) via Doola — NAICS codes, submit, track status, download documents.
- [identity](https://usenaive.ai/docs/cli/identity.md): View agent identity, provisioned resources, and available email inboxes.
- [images](https://usenaive.ai/docs/cli/images.md): Generate AI images or search stock photos — with full parameter passthrough.
- [jobs](https://usenaive.ai/docs/cli/jobs.md): Monitor and manage async jobs (image/video generation, deep research) with structured output.
- [CLI Overview](https://usenaive.ai/docs/cli/overview.md): The naive CLI — an agent-native command-line toolkit for email, search, AI generation, and business operations.
- [register / login / link](https://usenaive.ai/docs/cli/register.md): Create, authenticate, or link a Naive account from the CLI.
- [reviews](https://usenaive.ai/docs/cli/reviews.md): Reviews and reputation primitives via CLI: Google, Trustpilot, TripAdvisor, and social engagement.
- [search](https://usenaive.ai/docs/cli/search.md): Web search, URL extraction, and deep multi-source research with structured agent output.
- [seo](https://usenaive.ai/docs/cli/seo.md): Keyword research, backlink analysis, and competitive intelligence from the CLI.
- [social](https://usenaive.ai/docs/cli/social.md): Social media — connect accounts, create posts, schedule content, view analytics.
- [travel](https://usenaive.ai/docs/cli/travel.md): Travel discovery primitives via CLI: Google Hotels and TripAdvisor search.
- [Verification](https://usenaive.ai/docs/cli/verification.md): Identity verification (KYC) for company founders/members via Footprint — start, track, complete, and resend.
- [video](https://usenaive.ai/docs/cli/video.md): Generate AI videos — text-to-video and image-to-video with async job processing.
- [GEO/AEO](https://usenaive.ai/docs/getting-started/aeo.md): AI search optimization data - LLM responses, mentions tracking, AI keyword volume, and ChatGPT scraping.
- [Mobile App Data](https://usenaive.ai/docs/getting-started/app-data.md): App rankings, reviews, and metadata from Google Play and the Apple App Store.
- [Authentication](https://usenaive.ai/docs/getting-started/authentication.md): API keys, Bearer token auth, onboarding flows, and error handling.
- [Billing & Credits](https://usenaive.ai/docs/getting-started/billing.md): Manage subscriptions, purchase credits, and understand pricing
- [Virtual Cards](https://usenaive.ai/docs/getting-started/cards.md): Issue virtual payment cards (Stripe Issuing or Reloadly prepaid), fund via checkout, assign to agents, and track transactions.
- [Credits](https://usenaive.ai/docs/getting-started/credits.md): Usage-based billing — how credits work, costs per operation, sync vs async charging.
- [Domain Management](https://usenaive.ai/docs/getting-started/domains.md): System domains, custom (BYOD) domains, and domain purchasing — register, verify DNS, buy new domains, and manage the foundation of your email identity.
- [E-commerce Data](https://usenaive.ai/docs/getting-started/ecommerce.md): Product listings, pricing, sellers, and reviews from Google Shopping and Amazon.
- [Email](https://usenaive.ai/docs/getting-started/email.md): The email primitive — create inboxes, send and receive mail through identity-aware addresses on your company's domain.
- [Company Formation](https://usenaive.ai/docs/getting-started/formation.md): Incorporate an LLC via Doola — submit formation with KYC-verified founders, track status, and download documents.
- [Image Generation](https://usenaive.ai/docs/getting-started/images.md): Two visual primitives: AI image generation and free stock photo search.
- [Introduction](https://usenaive.ai/docs/getting-started/introduction.md): Naive API v2 — a standalone agentic API built for autonomous AI agents and CLI consumption.
- [Jobs](https://usenaive.ai/docs/getting-started/jobs.md): Unified async job tracking for all long-running operations.
- [Quickstart](https://usenaive.ai/docs/getting-started/quickstart.md): Register an agent, verify your domain, and call your first primitive in under 5 minutes.
- [Reviews](https://usenaive.ai/docs/getting-started/reviews.md): Reputation and review intelligence from Google, Trustpilot, TripAdvisor, and social engagement signals.
- [Web Research](https://usenaive.ai/docs/getting-started/search.md): Three research tools at different depths — web search, URL extraction, and multi-step deep research with citations.
- [SEO](https://usenaive.ai/docs/getting-started/seo.md): Keyword research, backlink analysis, and competitive intelligence covering Google, Bing, Amazon, and Google Trends.
- [Social Media](https://usenaive.ai/docs/getting-started/social.md): Post to 10+ social platforms — connect accounts, create posts, schedule content, and track analytics.
- [Travel](https://usenaive.ai/docs/getting-started/travel.md): Travel discovery and hotel intelligence from Google Hotels and TripAdvisor.
- [Identity Verification](https://usenaive.ai/docs/getting-started/verification.md): KYC identity verification for company founders/members via Footprint — hosted links, email delivery, and real-time status tracking.
- [Video Generation](https://usenaive.ai/docs/getting-started/video.md): Generate video — text-to-video and image-to-video using models like Kling, Minimax, and Wan.
- [Connection Guide](https://usenaive.ai/docs/mcp/connection.md): How to connect different MCP clients to the Naive hosted server.
- [MCP Server](https://usenaive.ai/docs/mcp/overview.md): Hosted Model Context Protocol server — connect Claude, Cursor, or any MCP client.
- [MCP Tools](https://usenaive.ai/docs/mcp/tools.md): All available MCP tools in the Naive API v2 hosted server.

## OpenAPI Specs

- [openapi](https://usenaive.ai/docs/api-reference/openapi.json)