> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Audio

> Upload a single audio chunk as a raw binary body. For `chunked` uploads, call this repeatedly with sequentially numbered filenames (`audio_0.webm`, `audio_1.webm`, ...); the server stores each chunk by its sequence number. For `single` uploads, send one complete recording and the server performs Voice Activity Detection (VAD) chunking inline. The `Content-Type` header should be the audio MIME type; if omitted it is inferred from the file extension.


Upload audio to a session as a **raw binary body** (not multipart/form-data, not JSON). The filename is supplied in the URL path and determines how the chunk is stored. This is the path for sessions created with `upload_type: chunked`.

<Info>
  The `Content-Type` header should be the audio MIME type (e.g. `audio/webm;codecs=opus`). If omitted, it is inferred from the file extension.
</Info>

<Note>
  Streaming over a WebSocket instead? Create the session with `upload_type: stream` and use [Stream Audio](/api-reference/health-ai/ekascribe/protocol/stream-audio). For single full-file / batch uploads, use the [SDKs](/api-reference/health-ai/ekascribe/quick-start) or the [deprecated EkaScribe v2 APIs](/api-reference/health-ai/ekascribe/ekascribe-v2/overview).
</Note>

## Path parameters

| Parameter    | Description                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `session_id` | The `session_id` returned by [Create Session](/api-reference/health-ai/ekascribe/protocol/create-session). |
| `file_name`  | Audio filename with extension. For chunked uploads use `<base>_<sequence>.<ext>` (e.g. `audio_0.webm`).    |

## Chunked upload flow

Call this endpoint **once per chunk**, in order, with sequentially numbered filenames:

```
POST /voice/v1/sessions/ses_abc123def456/audio/audio_0.webm
POST /voice/v1/sessions/ses_abc123def456/audio/audio_1.webm
POST /voice/v1/sessions/ses_abc123def456/audio/audio_2.webm
```

* Filename format: `<base>_<sequence>.<ext>` — the base name is arbitrary, the sequence number determines order.
* The server stores each chunk by its sequence number (e.g. `0.webm`, `1.webm`).

When all chunks are uploaded, call [End Session](/api-reference/health-ai/ekascribe/protocol/end-session) and poll [Get Session](/api-reference/health-ai/ekascribe/protocol/get-session) for results.

## Supported audio formats

`audio/webm;codecs=opus` · `audio/wav` · `audio/ogg` · `audio/ogg;codecs=opus` · `audio/mp4` · `audio/m4a` · `audio/mp3`

## Limits

| Limit                      | Value        |
| -------------------------- | ------------ |
| Max chunk size             | 10 MB        |
| Recommended chunk duration | ≤ 20 seconds |

## Example request

```bash theme={null}
curl -X POST \
  "https://api.eka.care/voice/v1/sessions/ses_abc123def456/audio/audio_0.webm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: audio/webm;codecs=opus" \
  --data-binary "@chunk_0.webm"
```

## Error codes

| Status | `error.code`           | When                                               |
| ------ | ---------------------- | -------------------------------------------------- |
| 400    | `session_ended`        | The session was already ended (committed).         |
| 400    | `session_completed`    | Processing already finished (`success`/`failure`). |
| 400    | `invalid_audio_format` | The MIME type is not in the supported list.        |
| 404    | `session_not_found`    | The `session_id` does not exist.                   |
| 413    | `chunk_too_large`      | The chunk exceeds the maximum size.                |

## Next step

When all chunks are uploaded, call [End Session](/api-reference/health-ai/ekascribe/protocol/end-session).


## OpenAPI

````yaml POST /voice/v1/sessions/{session_id}/audio/{file_name}
openapi: 3.0.1
info:
  title: EkaScribe Protocol API (MedScribeAlliance v0.1)
  version: '0.1'
  description: >
    Session-based medical voice capture API implementing the MedScribeAlliance
    Protocol v0.1. Discover service capabilities, create a session, stream audio
    chunks, then end the session to trigger asynchronous transcription and
    structured-template extraction.
servers:
  - url: https://api.eka.care
    description: Production server
  - url: https://api.dev.eka.care
    description: Development server
security: []
paths:
  /voice/v1/sessions/{session_id}/audio/{file_name}:
    post:
      tags:
        - protocol
      summary: Upload Audio
      description: >
        Upload a single audio chunk as a raw binary body. For `chunked` uploads,
        call this repeatedly with sequentially numbered filenames
        (`audio_0.webm`, `audio_1.webm`, ...); the server stores each chunk by
        its sequence number. For `single` uploads, send one complete recording
        and the server performs Voice Activity Detection (VAD) chunking inline.
        The `Content-Type` header should be the audio MIME type; if omitted it
        is inferred from the file extension.
      parameters:
        - name: session_id
          in: path
          required: true
          description: Session ID returned by Create Session
          schema:
            type: string
            example: ses_abc123def456
        - name: file_name
          in: path
          required: true
          description: >
            Audio filename with extension. For chunked uploads use
            `<base>_<sequence>.<ext>` (e.g. `audio_0.webm`, `audio_1.mp3`).
          schema:
            type: string
            example: audio_0.webm
        - name: Content-Type
          in: header
          required: false
          description: Audio MIME type. Inferred from the file extension if omitted.
          schema:
            type: string
            example: audio/webm;codecs=opus
      requestBody:
        required: true
        description: >-
          Raw binary audio data (max 10 MB per chunk, ≤20s duration
          recommended).
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Audio uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                    example: ses_abc123def456
                  success:
                    type: boolean
                    example: true
                  original_filename:
                    type: string
                    example: audio_0.webm
        '400':
          description: Session ended, processing completed, or invalid audio format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Chunk too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - auth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: invalid_audio_format
            message:
              type: string
              description: Human-readable error message.
              example: Audio format 'audio/mp3' is not supported
            details:
              type: object
              additionalProperties: true
              description: Additional error context.
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````