> ## Documentation Index > Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt > Use this file to discover all available pages before exploring further. # Create Voice File Job > Create a new Voice File Job for audio transcription and optional translation. - Returns a presigned upload URI for your audio file - Optionally specify source language hints and target translation locales - Job starts in `CREATED` status — upload your file to begin processing - Requires a user or system API key bound to a workspace where Voice File Jobs are enabled Documentation: [Complete workflow guide with code examples](/voice-file/tutorial) ## OpenAPI ````yaml /openapi.yaml post /v1/external/voice-file/jobs openapi: 3.1.0 info: title: Tiro API description: AI-powered note-taking and voice file processing API version: 1.0.0 contact: name: Tiro Support email: support@tiro.ooo url: https://tiro.ooo servers: - url: https://api.tiro.ooo description: Production server security: - BearerAuth: [] tags: - name: Note description: Operations for managing notes and their paragraphs - name: Note Share Link description: Manage share links for notes - name: Note Summary description: Operations for retrieving note summaries - name: Note Document description: Template-based document generation from notes - name: Note Document Template description: Operations for managing note document templates - name: Folder description: Operations for retrieving folders - name: Voice File description: Operations for voice file processing - name: Word Memory description: > Manage word memories to improve voice transcription accuracy. Register important terms like company names, people's names, and product names so Tiro recognizes them precisely during recording. Each term has an `entry` and an optional `subEntry` (an alternate spelling or notation). Personal (User), workspace-shared (Workspace), and organization-shared (Organization) word memories are managed separately, and each scope supports bulk create/update/delete (up to 1000 items per request). - name: Wiki description: | Access workspace wikis — unified knowledge graphs built from notes. Requires a workspace with wiki plan and activation enabled. - name: Organization description: > Endpoints for organization API keys. An organization key is issued by an organization admin, carries fixed scopes chosen at issuance, and can reach the notes in every workspace that belongs to the organization. Built for server-to-server integrations such as CRM sync — receive `note.ended` webhook events, generate documents for notes, and reconcile with the organization notes list. - name: Organization Management description: Operations for the authenticated user's organization. paths: /v1/external/voice-file/jobs: post: tags: - Voice File summary: Create Voice File Job description: > Create a new Voice File Job for audio transcription and optional translation. - Returns a presigned upload URI for your audio file - Optionally specify source language hints and target translation locales - Job starts in `CREATED` status — upload your file to begin processing - Requires a user or system API key bound to a workspace where Voice File Jobs are enabled Documentation: [Complete workflow guide with code examples](/voice-file/tutorial) operationId: createVoiceFileJob requestBody: description: > Optional parameters for transcription and translation. - If `transcriptLocaleHints` is omitted, language is auto-detected from audio - If `translationLocales` is omitted, no translations are generated required: false content: application/json: schema: type: object properties: transcriptLocaleHints: type: array items: type: string maxItems: 1 description: | Locale hints for transcription. - Maximum 1 locale - If omitted, language is auto-detected from audio content example: - en_US translationLocales: type: array items: type: string maxItems: 5 description: Optional locales for translation (max 5) example: - ko_KR - ja_JP responses: '201': description: Job created successfully content: application/json: schema: $ref: '#/components/schemas/VoiceFileJobCreated' examples: korean_to_english: summary: Korean audio with English translation value: id: b2d1ab32-3fe2-4201-b0b4-391abdbaa023 uploadUri: https://storage.example.com/upload/signed-url-abc123 multilingual: summary: English audio with multiple translations value: id: c3e2bc43-4gf3-5312-c1c5-402bcecbb134 uploadUri: https://storage.example.com/upload/signed-url-xyz789 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: > `403000 forbidden` when the key is not workspace-bound or the workspace policy is disabled. Bind the key to an enabled workspace or ask a Tiro administrator to enable Voice File Jobs. `403013 forbidden` when the key lacks `voice_file_job:write`. Reissue the key with the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: VoiceFileJobCreated: type: object description: > Response returned when a new Voice File Job is created. Contains the job ID and a presigned URL for uploading the audio file. **Next Steps:** 1. Upload your audio file to `uploadUri` using HTTP PUT 2. Call `PUT /v1/external/voice-file/jobs/{id}/upload-complete` to start processing required: - id - uploadUri properties: id: type: string description: >- Unique job identifier (UUID format). Use this ID in subsequent API calls. example: b2d1ab32-3fe2-4201-b0b4-391abdbaa023 uploadUri: type: string format: uri description: | Presigned URL for uploading the audio file. - Use HTTP PUT method to upload - URL expires in 1 hour - Set appropriate Content-Type header (e.g., audio/mpeg, audio/wav) example: >- https://tiro-uploads.s3.amazonaws.com/voice-files/job-abc123?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=... Error: type: object required: - error properties: error: type: object required: - code - errorType - message properties: code: type: integer description: > 6-digit error code in `AAABBB` form: first 3 digits match the HTTP status, last 3 digits are a per-status serial (e.g. `404018`). Use only when you need to distinguish specific error cases within the same HTTP status — values may be added or renumbered across releases. For general client branching, prefer `errorType`. example: 404018 errorType: type: string description: > Stable, coarse-grained error category. Recommended default for client-side branching: the value-to-status mapping is part of the API contract and will not change without a breaking-change notice. Typical use: - `unauthorized` → trigger re-authentication - `forbidden` → surface a permission error to the user - `not_found` → treat as missing resource - `too_many_requests` → back off and retry - `internal_error` → retry with exponential backoff enum: - bad_request - unauthorized - forbidden - not_found - not_acceptable - conflict - payload_too_large - unprocessable_entity - too_many_requests - internal_error example: not_found message: type: string description: >- Human-readable error message. Not stable; do not use for branching. example: 'No team found for user #217' detail: type: string nullable: true description: Additional error details example: null securitySchemes: BearerAuth: type: http scheme: bearer description: > API key in format `{id}.{secret}`. The notes an endpoint returns depend on the key type. A **user key** reaches the notes that user can see in the app, including notes in their own private folders. A **system key** (workspace or organization, no user identity) reaches only notes that sit in a folder shared with all workspace members. Notes in a private folder, in a folder shared with only some members, or in no folder at all fall outside a system key's read scope, and scopes do not widen that boundary. List and search endpoints drop out-of-scope notes from the response without an error. Single-note reads and their sub-resources return `404`, the same response as a deleted note. See [What notes a system key reads](https://docs.tiro.ooo/en/developers/fundamentals/system-key-note-scope). ````