> ## 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. # Would this action be allowed, and what decides > REAL and PURE — no side effect, no ledger row, nothing enqueued, nothing metered, and `side_effects: []` on the wire so a caller does not have to take the documentation's word for it. The primitive tier is the GOVERNOR's own verdict, over the same client the gate uses and with the same `strict` flag the gate would set for that primitive. The capability and approval tiers are re-derived, because the governor evaluates those inside a guarded evaluation that PERSISTS an approvals row when it freezes: an explain that called it would write one every time somebody asked a question. `tiers` names which is which, and which tiers (budget, freeze, connections, revocation, the actor test) this answer does not consult at all. A governor that is unreachable yields `verdict: "unavailable"` rather than the gate's 403, because the endpoint you run to find out why you were refused cannot itself be refused. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/policy/explain 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 Studio 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: Studio 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: Google Business, Trustpilot, TripAdvisor, social data (passthrough). - 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. paths: /v1/policy/explain: post: tags: - Governance summary: Would this action be allowed, and what decides description: >- REAL and PURE — no side effect, no ledger row, nothing enqueued, nothing metered, and `side_effects: []` on the wire so a caller does not have to take the documentation's word for it. The primitive tier is the GOVERNOR's own verdict, over the same client the gate uses and with the same `strict` flag the gate would set for that primitive. The capability and approval tiers are re-derived, because the governor evaluates those inside a guarded evaluation that PERSISTS an approvals row when it freezes: an explain that called it would write one every time somebody asked a question. `tiers` names which is which, and which tiers (budget, freeze, connections, revocation, the actor test) this answer does not consult at all. A governor that is unreachable yields `verdict: "unavailable"` rather than the gate's 403, because the endpoint you run to find out why you were refused cannot itself be refused. parameters: - name: tenant in: query required: false schema: type: string description: Tenant user id. Absent, the caller's own subject answers. requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string description: Action id, e.g. "cards.create". toolkit: type: string description: For the connection family. payload: type: object additionalProperties: true responses: '200': description: The verdict, and the layer and rule that produced it. content: application/json: schema: type: object properties: action: type: string tenant_user_id: type: string environment: type: string verdict: type: string enum: - allow - deny - park - attest - unavailable description: >- The ENGINE's verdict vocabulary. `approve` is what a rule author writes; it folds to `park`. because: type: object properties: layer: type: string rule: type: string nullable: true detail: type: string primitive: type: string primitive_enabled: type: boolean capability_allowed: type: boolean requires_approval: type: boolean tiers: type: object additionalProperties: true description: >- Which tiers this answer consulted (`consulted`), which it re-derived rather than asked the governor for (`reimplemented`), and which it did not evaluate at all (`not_consulted`). A caller that cannot tell those apart cannot judge how much to trust the verdict. side_effects: type: array items: type: string '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/Unauthorized' components: responses: InvalidInput: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: nv_sk_live_... description: Workspace API key. Create one via the dashboard or `POST /v1/auth/keys`. ````