> ## 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. # Start an agent run > Opens a run in the agent-run ledger. When the run carries an objective and attach_brain is not false, an ambient brain capsule is attached best-effort and returned alongside the run. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/runs 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/runs: post: tags: - Orchestration summary: Start an agent run description: >- Opens a run in the agent-run ledger. When the run carries an objective and attach_brain is not false, an ambient brain capsule is attached best-effort and returned alongside the run. requestBody: required: false content: application/json: schema: type: object properties: tenant_user_id: type: string format: uuid description: >- Defaults to the caller's resolved subject user id, else null. objective_id: type: string format: uuid ceo_message_id: type: string format: uuid task_id: type: string format: uuid task_run_id: type: string format: uuid parent_run_id: type: string format: uuid run_type: type: string enum: - ceo - hermes - worker - tool - maintenance - manual default: manual status: type: string enum: - queued - running - blocked - completed - failed - cancelled default: running requested_by: type: object description: >- Defaults to the calling principal (agent key, owner session, or system). properties: type: type: string enum: - owner - ceo - agent - system id: type: string maxLength: 255 nullable: true required: - type assigned_profile: type: string maxLength: 255 agent_id: type: string format: uuid model: type: string maxLength: 255 runtime: type: string maxLength: 255 external_runtime_id: type: string maxLength: 255 description: >- Unique per (company, runtime); reusing one linked to another run returns 409. objective: type: string maxLength: 4000 metadata: type: object additionalProperties: true attach_brain: type: boolean description: Set false to skip the ambient brain capsule. brain_knowledge_base_id: type: string format: uuid brain_since_watermark: type: string format: date-time description: Previous capsule's as_of, to receive deltas since then. responses: '201': description: Run created. content: application/json: schema: type: object properties: run: type: object description: Serialised agent run (contracts/brain-ops.ts formatRun). properties: id: type: string format: uuid tenant_user_id: type: string format: uuid nullable: true objective_id: type: string format: uuid nullable: true ceo_message_id: type: string format: uuid nullable: true task_id: type: string format: uuid nullable: true task_run_id: type: string format: uuid nullable: true parent_run_id: type: string format: uuid nullable: true run_type: type: string enum: - ceo - hermes - worker - tool - maintenance - manual status: type: string enum: - queued - running - blocked - completed - failed - cancelled requested_by: type: object nullable: true description: Null when the run row has no requested_by_type. properties: type: type: string enum: - owner - ceo - agent - system id: type: string nullable: true assigned_profile: type: string nullable: true agent_id: type: string format: uuid nullable: true model: type: string nullable: true runtime: type: string nullable: true external_runtime_id: type: string nullable: true objective: type: string nullable: true summary: type: string nullable: true error: type: string nullable: true spend: type: object additionalProperties: true nullable: true token_usage: type: object additionalProperties: true nullable: true metadata: type: object additionalProperties: true nullable: true started_at: type: string format: date-time nullable: true ended_at: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - run_type - status - created_at - updated_at brain_capsule: type: object nullable: true description: >- Ambient brain capsule attached when the run has an objective and attach_brain is not false. Null when no objective, when opted out, or when the (best-effort) attach failed. properties: space: type: object properties: knowledge_base_id: type: string scope_kb_ids: type: array items: type: string required: - knowledge_base_id - scope_kb_ids as_of: type: string description: >- Watermark; echo back as brain_since_watermark on the next attach. beliefs: type: array items: type: object properties: id: type: string description: Capsule label, B1..Bn. claim_id: type: string statement: type: string subject: type: string predicate: type: string object: type: string confidence: type: number status: type: string valid_from: type: string nullable: true valid_to: type: string nullable: true observed_at: type: string updated_at: type: string supersedes_claim_id: type: string nullable: true required: - claim_id - statement - subject - predicate - object - confidence - status - valid_from - valid_to working_set: type: array items: type: object properties: id: type: string kind: type: string title: type: string object_id: type: string required: - id - kind - title - object_id deltas: type: object properties: newly_active: type: array items: type: object properties: id: type: string description: Capsule label, B1..Bn. claim_id: type: string statement: type: string subject: type: string predicate: type: string object: type: string confidence: type: number status: type: string valid_from: type: string nullable: true valid_to: type: string nullable: true observed_at: type: string updated_at: type: string supersedes_claim_id: type: string nullable: true required: - claim_id - statement - subject - predicate - object - confidence - status - valid_from - valid_to invalidated: type: array items: type: object properties: id: type: string description: Capsule label, B1..Bn. claim_id: type: string statement: type: string subject: type: string predicate: type: string object: type: string confidence: type: number status: type: string valid_from: type: string nullable: true valid_to: type: string nullable: true observed_at: type: string updated_at: type: string supersedes_claim_id: type: string nullable: true required: - claim_id - statement - subject - predicate - object - confidence - status - valid_from - valid_to required: - newly_active - invalidated open_questions: type: array items: type: string citation_map: type: object additionalProperties: type: string description: >- Maps capsule belief label (e.g. B7) to claim id; echo back with debrief.contradicts. capsule_id: type: string render: type: string description: Prose rendering of the capsule; read this first. required: - space - as_of - beliefs - working_set - deltas - open_questions - citation_map - capsule_id - render required: - run - brain_capsule '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/Unauthorized' '409': description: >- external_runtime_id is already linked to another run (code duplicate_record). content: application/json: schema: $ref: '#/components/schemas/Error' deprecated: true 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`. ````