> ## Documentation Index > Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search local listings (Google Maps) > Normalized local-listing search from Google Maps — the second provider on this primitive, and unlike the DataForSEO routes beside it this returns Place objects rather than the vendor's task envelope, names the provider that answered, and bills 2x the provider run's real cost. DOES NOT RETURN CONTACT PEOPLE. The provider will also scrape named contacts with work emails; that request is never sent. Contact data is the People primitive, which carries the opt-in gate, the B2B-only field filter and an erasure path. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/business/places/search openapi: 3.0.3 info: title: Naïve API version: 2.0.0 description: >- Naïve gives every AI agent its own governed real-world agent profile — a verified business identity (EIN/formation), a spend-capped card, an inbox and phone number, and a place to run — provisioned per end-user, governed on every action, and instantly revocable. This API exposes agent profile provisioning + the underlying regulated primitives (identity, money, comms) and the governance gateway. ## Authentication All endpoints (except `/health`, `/skill.md`, `/register.md`, and the `/v1/auth/*` onboarding routes) require a workspace API key: ``` Authorization: Bearer nv_sk_live_... ``` Many control-plane endpoints also accept a browser session cookie (`naive_session`) for the dashboard. ## Per-user data plane Nearly every primitive is available at two mount points: - **Company-level** — e.g. `GET /v1/email/inboxes`, scoped to the account's default agentProfile. - **Per-user** — e.g. `GET /v1/users/{user_id}/email/inboxes`, scoped to a specific end-user (`tenant_user`). Pass `default` or `me` as `{user_id}` to target the account's own default agentProfile. This spec documents the canonical company-level path for each primitive plus the per-user-only primitives (connections, vault, sessions, browser). Every per-user variant accepts the same request/response shapes. ## Errors All errors share one envelope: ```json { "error": { "code": "invalid_input", "message": "Human readable description", "hint": "Actionable next step for the agent" } } ``` `code` maps 1:1 to the HTTP status. Rate-limit responses include a `Retry-After` header. servers: - url: https://api.usenaive.ai description: Production - url: http://localhost:3101 description: Local development security: - bearerAuth: [] tags: - name: Auth & Onboarding description: Registration, login, sessions, and API key management. - name: Identity description: Authenticated agent identity, resources, and credit balance. - name: AgentProfiles description: >- Provision and govern a real-world agent profile per tenant (identity, money, comms, runtime). Provisioning is idempotent and revoke is absolute. - name: Projects description: >- Projects — the scope between an organization and its account kits and child projects. Every organization has a default project that un-projected calls resolve to. - name: Users description: Tenant users (each tenant's agent profile subject). - name: AccountKits description: Reusable primitive + connection policy bundles assigned to users. - name: Connections description: Composio toolkit connections (OAuth / API key) per user. - name: Vault description: Envelope-encrypted per-user secret storage. - name: Logs description: Activity audit events. - name: Approvals description: Human-in-the-loop approval queue for agent actions. - name: Sessions description: Revocable MCP session tokens scoped to a tenant user. - name: Orchestration description: CEO runs, tasks, objectives, employees, cron, and memory. - name: Templates description: Business templates that scaffold agents, tasks, and apps. - name: Template Apps description: Installable template app instances. - name: Apps description: Deployable apps (Vercel + Supabase) with secrets, domains, and proxies. - name: Compute description: ECS/Fargate compute resources (services, jobs, schedules). - name: Queue description: SQS-backed message queues. - name: Mobile description: >- Cloud mobile emulators/devices (Mobilerun): provision phones, run agent tasks, stream live, and reach the whole device API via a wildcard. - name: Sandbox description: >- Disposable micro-VM code sandboxes — exec, files, ports, checkpoint, fork, park/sleep & resume. Usage billed from credits (observed CPU/memory/disk + a one-time creation fee). - name: Files description: Read and download files from a company container workspace. - name: Dashboard description: Dashboard aggregates and credit usage. - name: Playground description: Claude Agent SDK chat scoped to the default tenant user. - name: Domains description: Domain registration, DNS records, and zone editing. - name: Billing description: Company subscription, plans, credit packs, and transactions. - name: Plans description: Developer-defined tenant plan definitions. - name: Tenant Billing description: Per-tenant-user subscription and usage. - name: Jobs description: Async job status and cancellation. - name: Status description: Account overview and usage. - name: Events description: Server-Sent Events stream of live company events. - name: Webhooks description: Webhook subscription management. - name: Email description: Inboxes and inbound/outbound email. - name: Phone description: Phone numbers and SMS (10DLC). - name: Social description: Social account connections and posts. - name: Verification description: KYC identity verification of company members. - name: Images description: Image generation, stock search, and models. - name: Video description: Video generation and models. - name: Clips description: AI video clipping. - name: Media description: Company media asset library. - name: Search description: Web search, URL reading, and research. - name: LLM description: OpenAI-compatible chat completions and models. - name: Audio description: >- Speech routing — transcription, speech synthesis, and native audio conversations. - name: Browser description: Agent-driven and human browser sessions. - name: Cards description: Virtual payment cards and Stripe Issuing. - name: Wallet description: >- Per-agent crypto wallets (USDC on Base): balance, funding, transfers, spend policy, and sweep. Mounted per-user only. Requires the opt-in `payments` primitive. - name: Payments description: >- x402 buy-side payments: quote a paywalled resource, pay for it from the agent's wallet, and read receipts. Requires the opt-in `payments` primitive. - name: Trading description: Brokerage (Alpaca) connections, orders, and positions. - name: Formation description: LLC formation via Doola. - name: SEO description: DataForSEO keywords, backlinks, and Labs (passthrough). - name: App Data description: App store (Google Play / Apple) data (passthrough). - name: Business Data description: >- Reviews & listings — Google Business, Trustpilot, TripAdvisor and travel (passthrough). Reputation and place intelligence; for the company itself see Company Data. - name: People description: >- B2B people search and work-contact enrichment. OPT-IN: disabled until an AccountKit enables `people`, with one exception — `GET /v1/people/terms` answers before you enable it, because it is what you read to decide. Metered on 3x the provider run's real spend; a no-match is billed too, because the run still happened. Not a consumer report — see GET /v1/people/terms and ToS Section 18. - name: Company Data description: >- Private-company firmographics, funding, investors, headcount and technology stack. Distinct from Business Data (Reviews & Listings), which covers reputation, and from /v1/companies, which is the tenant control plane. - name: Social Data description: >- READ public posts, comments and engagement on X, Reddit, Bluesky and Hacker News. Distinct from Social, which connects accounts and publishes. Reddit is asynchronous only — POST /v1/social-data/tasks. - name: AEO description: 'Answer-engine optimization: LLM responses, scraper, and mentions.' - name: E-commerce description: Google Shopping and Amazon product data (passthrough). - name: Runtime description: >- The durable runtime: teams, boards, runs, transcripts and the honesty report. - name: Governance description: >- Policy, grants, limits, spend, attestations and the resolved connection policy. - name: Brain description: Beliefs, lessons, levels and retention. - name: Deployments description: Application deployments. - name: Triggers description: Inbound triggers and hooks. - name: Vetta description: Inbound routes the durable runtime calls. - name: Voice description: Voice agents, cloning and consent. - name: Support description: >- Platform support: tickets from developers to the naive team, answered by the hosted support agent with human escalation. The /admin surface is restricted to naive-team session emails (SUPPORT_ADMIN_EMAILS). paths: /v1/business/places/search: post: tags: - Business Data summary: Search local listings (Google Maps) description: >- Normalized local-listing search from Google Maps — the second provider on this primitive, and unlike the DataForSEO routes beside it this returns Place objects rather than the vendor's task envelope, names the provider that answered, and bills 2x the provider run's real cost. DOES NOT RETURN CONTACT PEOPLE. The provider will also scrape named contacts with work emails; that request is never sent. Contact data is the People primitive, which carries the opt-in gate, the B2B-only field filter and an erasure path. parameters: - name: Idempotency-Key in: header required: false description: >- Deduplicates BOTH the response and the credit deduction: it becomes the ledger reference, so a retried call cannot be charged twice. Max 255 characters. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - query - location properties: query: type: string description: What to search for, e.g. 'dentist'. location: type: string description: >- REQUIRED, not defaulted: Maps results are location-scoped, so a query without one returns whatever Google infers from the datacentre the run happened in — a result the caller cannot reproduce. E.g. 'Austin, Texas'. limit: type: number default: 20 description: 1-100. Above 100, Maps itself stops paginating. responses: '200': description: OK. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BusinessPlace' credits_used: type: number description: >- 3x what the provider run actually cost, empty results included. A failed run is never billed. credits_remaining: type: number provider: type: string enum: - apify_google_maps - dataforseo description: >- Which vendor answered. Named because this primitive has two, and provenance is the subject. mock: type: boolean description: >- Present and true only when the response came from fixtures. '400': $ref: '#/components/responses/InvalidInput' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '501': description: >- Not configured — the Maps provider has no credential. Returned as feature_not_configured rather than an empty list, and points at the DataForSEO task routes on this primitive. components: schemas: BusinessPlace: type: object properties: place_id: type: string description: Google's stable place id. Pass to POST /v1/business/places/reviews. name: type: string categories: type: array items: type: string address: type: string city: type: string postal_code: type: string country_code: type: string latitude: type: number longitude: type: number phone: type: string website: type: string rating: type: number description: >- Mean rating. Absent when the listing has no reviews — absent and zero are different. reviews_count: type: number permanently_closed: type: boolean temporarily_closed: type: boolean url: type: string Error: type: object properties: error: type: object properties: code: type: string description: Canonical error kind, maps 1:1 to the HTTP status. enum: - unauthorized - forbidden - insufficient_credits - billing_blocked - rate_limited - invalid_inbox - resource_not_found - not_found - invalid_input - provider_error - job_not_ready - duplicate_request - duplicate_record - account_not_provisioned - feature_not_configured - not_configured - compliance_pending - payment_rejected - wallet_not_configured - internal_error message: type: string hint: type: string reason: type: string description: Optional granular reason code. required: - code - message required: - error responses: InvalidInput: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: Insufficient credits or billing blocked. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The resolved AccountKit disables this primitive, or the caller lacks permission. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: nv_sk_live_... description: Workspace API key. Create one via the dashboard or `POST /v1/auth/keys`. ````