> ## 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. # Create a transcription > Transcribe audio (speech to text). Accepts a `multipart/form-data` upload with the audio in the `file` field, or an `application/json` body with base64 `input_audio`. Multipart requests take the same fields as form values, but `provider`, `metadata`, `options`, and `keyterms` must be JSON-encoded strings. `response_format` of `text`, `srt`, or `vtt` returns a plain-text body instead of the transcription object. Add `?async=true` to queue the job and get a 202 with a request id to poll. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/audio/transcriptions 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). - name: Agents description: >- Long-horizon agents: create, configure, send work, read the task and event log, deliverables, spend and webhooks. - name: Organization description: 'Organization membership: members, invitations and leaving.' - name: Company description: 'Company membership: members, invitations and leaving.' - name: Cron description: >- Scheduled internal jobs invoked by the platform's own timer, not by customers. paths: /v1/audio/transcriptions: post: tags: - Audio summary: Create a transcription description: >- Transcribe audio (speech to text). Accepts a `multipart/form-data` upload with the audio in the `file` field, or an `application/json` body with base64 `input_audio`. Multipart requests take the same fields as form values, but `provider`, `metadata`, `options`, and `keyterms` must be JSON-encoded strings. `response_format` of `text`, `srt`, or `vtt` returns a plain-text body instead of the transcription object. Add `?async=true` to queue the job and get a 202 with a request id to poll. parameters: - name: async in: query required: false description: >- Queue the transcription and return 202 with a request id instead of waiting. Recommended for long audio. schema: type: string enum: - 'true' - '1' requestBody: required: true content: application/json: schema: type: object required: - input_audio properties: input_audio: type: object description: >- Base64 audio (JSON requests only). Mutually exclusive with the multipart `file` field. required: - data - format properties: data: type: string description: Base64 audio, with no data-URL prefix. format: type: string description: Container/encoding, e.g. wav, mp3, flac, ogg. sample_rate: type: integer channels: type: integer model: type: string description: >- Exact `owner/model` slug, or `auto` / `stt/auto` for managed routing. default: auto language: type: string description: >- BCP-47 hint (e.g. es, pt-BR). On a managed route this skips language detection — lower latency and better accuracy. prompt: type: string description: >- Context or vocabulary hint for models that support prompting. response_format: type: string enum: - json - verbose_json - text - srt - vtt - diarized_json default: json temperature: type: number timestamps: type: string enum: - none - segment - word - both diarize: type: boolean description: Label speakers. Speaker ids are normalized to spk_N. redact: type: boolean description: Redact detected PII where supported. translate: type: boolean description: Translate the transcript to English where supported. keyterms: type: array items: type: string retention: type: string enum: - none - transcript - debug - archive thinking: type: string enum: - minimal - low - medium - high metadata: type: object additionalProperties: true provider: type: object description: Per-request routing constraints, applied before ranking. properties: only: type: array items: type: string description: Allow-list of owners, models, or endpoints. ignore: type: array items: type: string description: Block-list of owners, models, or endpoints. order: type: array items: type: string description: >- Preferred candidates, tried ahead of the ranked remainder. allow_fallbacks: type: boolean description: >- Retry the next candidate on a retryable error. Defaults true for aliases, false for pinned models. require_features: type: boolean description: >- Drop candidates that cannot satisfy every requested feature instead of degrading. max_price: type: object description: >- Price ceiling. `per_min` caps transcription per audio minute; `per_1k_chars` caps speech per 1,000 input characters. properties: per_min: type: number per_1k_chars: type: number region: type: array items: type: string description: >- Keep candidates serving one of these regions; `global` always matches. options: type: object additionalProperties: true description: >- Native model controls, namespaced per owner. Applied only when the request resolves to that owner. multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: The audio file. model: type: string description: >- Exact `owner/model` slug, or `auto` / `stt/auto` for managed routing. default: auto language: type: string description: >- BCP-47 hint (e.g. es, pt-BR). On a managed route this skips language detection — lower latency and better accuracy. prompt: type: string description: >- Context or vocabulary hint for models that support prompting. response_format: type: string enum: - json - verbose_json - text - srt - vtt - diarized_json default: json temperature: type: number timestamps: type: string enum: - none - segment - word - both diarize: type: boolean description: Label speakers. Speaker ids are normalized to spk_N. redact: type: boolean description: Redact detected PII where supported. translate: type: boolean description: Translate the transcript to English where supported. keyterms: type: array items: type: string retention: type: string enum: - none - transcript - debug - archive thinking: type: string enum: - minimal - low - medium - high metadata: type: object additionalProperties: true provider: type: object description: Per-request routing constraints, applied before ranking. properties: only: type: array items: type: string description: Allow-list of owners, models, or endpoints. ignore: type: array items: type: string description: Block-list of owners, models, or endpoints. order: type: array items: type: string description: >- Preferred candidates, tried ahead of the ranked remainder. allow_fallbacks: type: boolean description: >- Retry the next candidate on a retryable error. Defaults true for aliases, false for pinned models. require_features: type: boolean description: >- Drop candidates that cannot satisfy every requested feature instead of degrading. max_price: type: object description: >- Price ceiling. `per_min` caps transcription per audio minute; `per_1k_chars` caps speech per 1,000 input characters. properties: per_min: type: number per_1k_chars: type: number region: type: array items: type: string description: >- Keep candidates serving one of these regions; `global` always matches. options: type: object additionalProperties: true description: >- Native model controls, namespaced per owner. Applied only when the request resolves to that owner. responses: '200': description: >- The transcription. `text`/`srt`/`vtt` formats return a plain-text body instead. content: application/json: schema: type: object properties: id: type: string object: type: string example: transcription created: type: integer model: type: string description: The model you requested. resolved_model: type: string description: >- The model that served the request. Managed routes report `auto`. provider: type: string text: type: string language: type: string nullable: true duration: type: number nullable: true description: Audio duration in seconds. segments: type: array items: type: object additionalProperties: true words: type: array items: type: object additionalProperties: true speakers: type: array items: type: object additionalProperties: true entities: type: array items: type: object additionalProperties: true usage: type: object description: >- Normalized usage. `cost` is in USD; Naive credits are reported separately as credits_used. properties: seconds: type: number billable_seconds: type: integer input_seconds: type: number output_seconds: type: number input_chars: type: integer cost: type: number currency: type: string route: type: object description: How the model was selected, and what was attempted. properties: mode: type: string description: auto, alias, or exact. reason: type: string candidates: type: integer description: Eligible candidates after filtering. filtered: type: array items: type: object additionalProperties: true attempts: type: array items: type: object additionalProperties: true description: >- One entry per attempted candidate: provider, model, endpoint, status, latency_ms, error_code. warnings: type: array items: type: string credits_used: type: number description: Naive credits charged for this request. credits_remaining: type: number text/plain: schema: type: string '202': description: Queued (async=true). Poll GET /v1/audio/transcriptions/{id}. content: application/json: schema: type: object properties: id: type: string status: type: string enum: - queued - running - succeeded - failed - canceled '400': $ref: '#/components/responses/InvalidInput' '402': $ref: '#/components/responses/PaymentRequired' components: 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' 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 - llm_routing_requires_payment - 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. block_reason: type: string description: >- Why this company may not spend. The first five accompany `billing_blocked` and stop every primitive. `llm_routing_requires_payment` differs in both directions: it stops exactly one primitive, and it is also the `code` — the same string in both fields on purpose, so a consumer that switches on the reason needs no mapping from the code. It means the balance is entirely free credit (the signup grant, or credit that was comped) and LLM routing is the one primitive free credit cannot buy. Cleared by buying credit (`POST /v1/billing/topup`) or subscribing (`POST /v1/billing/subscribe`); never by verifying an email and never by being granted more free credit. enum: - no_subscription - trial_expired - subscription_cancelled - subscription_past_due - credits_exhausted - llm_routing_requires_payment credit_kind: type: string description: >- Present on `llm_routing_requires_payment`: the kind of credit the balance is made of, and therefore why it does not qualify. `trial` means the signup grant or a comped grant. enum: - trial balance: type: number description: >- The company's credit balance at the moment of the refusal, in credits. Carried on `llm_routing_requires_payment` precisely because it is NOT the problem — see `balance_note`. balance_note: type: string description: >- Says in words that the balance is not what was refused. Without it the response reads as a contradiction ("I hold credit and you refused me") and the obvious next move — collect more free credit — is the one move that provably cannot work. actions: type: object additionalProperties: type: string description: >- The calls that clear this refusal, keyed by a stable id (`topup`, `subscribe`, `view_plans`). Each value is a method and path. They start a payment, so they are a human's to run. 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`. ````