> ## 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. # Get brain runtime status > Operator view of the brain runtime: providers, model config, service health, KB and document counts. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/users/{user_id}/brain/status 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/users/{user_id}/brain/status: get: tags: - Brain summary: Get brain runtime status description: >- Operator view of the brain runtime: providers, model config, service health, KB and document counts. parameters: - $ref: '#/components/parameters/UserId' - $ref: '#/components/parameters/NaiveProjectId' responses: '200': description: Runtime status. content: application/json: schema: type: object properties: provider: type: string semantic_engine: type: string enum: - postgres - gbrain description: >- The configured preference, not what is running. Defaults to `postgres`. Whether a semantic engine is actually in the read path is services.gbrain.configured. models: type: object properties: embedding: type: string nullable: true description: >- The embedding model that would actually be sent. Null on a mock or unresolved leg. embedding_dim: type: integer description: >- Vector width of the brain_chunks column. Always a number, on every rung. reranker: type: string nullable: true description: Rerank model, or null when no reranker resolved. answer: type: string nullable: true description: >- The synthesis model that would actually be sent, or null when no answerer resolved. additionalProperties: true services: type: object properties: embedding: type: object properties: name: type: string description: 'Stable identifier: `brain_embeddings`.' configured: type: boolean description: >- A resolution rung answered, so calls to this leg will be attempted. Derived from the same resolution the call path uses, so it cannot disagree with what an ingest or query does. source: type: string nullable: true enum: - mock - explicit - openai-default - null description: >- Which resolution rung answered: `explicit` (BRAIN_EMBED_BASE) or `openai-default` (OPENAI_API_KEY). `mock` under BRAIN_MOCK. Null when nothing resolved. ok: type: boolean description: >- The live probe issued by this call succeeded. Always false when `configured` is false. latency_ms: type: integer description: >- Probe latency. Present only when a probe was issued - absent for `mock` and for an unresolved leg. error: type: string description: >- Present only when `ok` is false: `not_configured`, `invalid_base_url` (a base URL is set but does not parse), `http_`, or the fetch error text. additionalProperties: true answerer: type: object properties: name: type: string description: 'Stable identifier: `brain_answerer`.' configured: type: boolean description: >- A resolution rung answered, so calls to this leg will be attempted. Derived from the same resolution the call path uses, so it cannot disagree with what an ingest or query does. source: type: string nullable: true enum: - mock - explicit - openrouter-default - null description: >- Which resolution rung answered: `explicit` (BRAIN_ANSWER_BASE) or `openrouter-default` (OPENROUTER_API_KEY). `mock` under BRAIN_MOCK. Null when nothing resolved. ok: type: boolean description: >- The live probe issued by this call succeeded. Always false when `configured` is false. latency_ms: type: integer description: >- Probe latency. Present only when a probe was issued - absent for `mock` and for an unresolved leg. error: type: string description: >- Present only when `ok` is false: `not_configured`, `invalid_base_url` (a base URL is set but does not parse), `http_`, or the fetch error text. synthesis_failures_since_boot: type: integer description: >- Synthesis attempts that fell back to `grounded` in this API process since it started. Present only when non-zero, and only on this leg. It exists because `ok` is a weaker signal here than on the embedding leg: on `openrouter-default` the probe is GET https://openrouter.ai/api/v1/key, which rejects a revoked key but returns 200 for a valid key that has no credits - while every synthesis 402s. A green `ok` with this value climbing means the credential is live and the calls are not. optional: type: boolean enum: - true description: >- Always true on this service. Present on the `answerer` and `reranker` legs only — never on `embedding` or `gbrain`. Absence of the leg is not a fault: the query path degrades and keeps answering, and this leg is not part of `ready`. additionalProperties: true reranker: type: object properties: name: type: string description: 'Stable identifier: `tei_reranker`.' configured: type: boolean description: >- A resolution rung answered, so calls to this leg will be attempted. Derived from the same resolution the call path uses, so it cannot disagree with what an ingest or query does. source: type: string nullable: true enum: - mock - explicit - null description: >- Which resolution rung answered: `explicit` (BRAIN_RERANK_BASE), or `mock` under BRAIN_MOCK. There is deliberately no hosted rung, so null is the normal value and retrieval keeps its RRF fusion order. ok: type: boolean description: >- The live probe issued by this call succeeded. Always false when `configured` is false. latency_ms: type: integer description: >- Probe latency. Present only when a probe was issued - absent for `mock` and for an unresolved leg. error: type: string description: >- Present only when `ok` is false: `not_configured`, `invalid_base_url` (a base URL is set but does not parse), `http_`, or the fetch error text. optional: type: boolean enum: - true description: >- Always true on this service. Present on the `answerer` and `reranker` legs only — never on `embedding` or `gbrain`. Absence of the leg is not a fault: the query path degrades and keeps answering, and this leg is not part of `ready`. additionalProperties: true gbrain: type: object properties: name: type: string configured: type: boolean description: >- True only when BRAIN_SEMANTIC_ENGINE=gbrain AND a GBrain base URL is set. ok: type: boolean details: type: object additionalProperties: true description: >- Optional semantic-engine sidecar. Different shape from the three inference services: no `source`, no `optional`. additionalProperties: true additionalProperties: true knowledge_bases: type: object properties: total: type: integer by_status: type: object additionalProperties: type: integer items: type: array items: type: object properties: id: type: string name: type: string provider: type: string status: type: string is_default: type: boolean created_at: type: string updated_at: type: string additionalProperties: true documents: type: object properties: total: type: integer by_status: type: object additionalProperties: type: integer recent: type: array items: type: object properties: id: type: string knowledge_base_id: type: string nullable: true filename: type: string nullable: true source: type: string nullable: true source_url: type: string nullable: true status: type: string bytes: type: integer nullable: true created_at: type: string updated_at: type: string additionalProperties: true projection: type: object properties: pending: type: integer failed: type: integer oldestPendingAt: type: string gbrainConfigured: type: boolean additionalProperties: true ready: type: boolean description: >- True when the embedding service is up, the projection queue has no failures, and - only if a semantic engine is configured - that engine is healthy. The answerer and the reranker are excluded on purpose: both are optional and a query still answers without them. timestamp: type: string additionalProperties: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: parameters: UserId: name: user_id in: path required: true description: >- Tenant user UUID, or `default` / `me` for the account's default agentProfile. schema: type: string NaiveProjectId: name: X-Naive-Project-Id in: header required: false description: >- Act inside this project. The header form of the `/v1/projects/{project_id}/...` prefix, for clients that cannot rewrite their base path. Lower precedence than the path, higher than the key's pinned project; omitted resolves to the organization's default project. schema: type: string format: uuid responses: Unauthorized: description: Missing or invalid credentials. 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' 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`. ````