Audio Upload - Store Audio Chunk

Service:
Dragon Copilot APIs
API Version:
2025-07-15

Uploads audio data with associated metadata for Dragon Copilot processing.
This endpoint accepts multipart/form-data containing two fields:

  • metadata (required): A JSON string identifying the partner, customer, product, ambient session, recording, and chunk number.
  • content (optional for first chunk): The binary audio data for this chunk.

Each chunk is identified by a chunkId starting from 2. The chunk: 1 may omit the binary content field if it is metadata-only. Chunks do not need to be uploaded in strict sequential order; the service accepts chunks as they arrive.

Prerequisite: Before calling this endpoint, you must create an ambient session via the Dragon Copilot Partner API (PUT /ambient-sessions) with the same correlationId. See Create Ambient Session for details. Requests that reference a non-existent session will fail.

After all chunks are uploaded, use the Finalize Audio Upload endpoint to signal that the complete recording is ready for processing.

Authentication: Requires a valid S2S Bearer token in the Authorization header. The calling application must be registered on the service allow list.

PUT https://ambient-audio-service.copilot.us.dragon.com/audio/storeChunk?api-version=2025-07-15

URI Parameters

Name In Required Type Description
api-version
 query True

string

API version. Must be 2025-07-15.

Request Header

Media Types: "multipart/form-data"

Name Required Type Description
Authorization True

string

Server-to-Server (S2S) machine-to-machine Bearer token (JWT). The recommended identity solution is Microsoft Entra ID, but the service accepts tokens from any identity provider that meets the JWT requirements and has been added to the service's allow list.

Format: Bearer <token>

All REST endpoints require a valid S2S token in the Authorization header. The token must be a JSON Web Token (JWT) whose issuer metadata is publicly available at <issuer>/.well-known/openid-configuration.

Validation flow:

  1. The service validates the JWT signature and standard claims (expiry, audience, issuer).
  2. The service checks the calling application's identity against a configured allow list (M2M inbound policy).
  3. Requests from unrecognized application identities are rejected with 401 Unauthorized.

Contact your Dragon partner relations team to register your identity provider on the allow list.
x-correlation-id True

string (uuid)

Correlation identifier used for end-to-end request tracing and diagnostics across services. This value is logged and propagated to downstream services, enabling you to trace the full lifecycle of a request.

Required -the service returns 400 Bad Request with {"error": "x-correlation-id header is required"} if this header is missing.

Request Body

Media Types: "multipart/form-data"

Name Required Type Description
metadata True

string

Audio chunk metadata as a JSON string.

Required fields: productId (uuid), partnerId (uuid), customerId (uuid), correlationId (uuid), recordingId (int, >= 1), chunkId (int, >= 1)

Optional fields: isLast (bool, default false), ehrInstanceId (string), externalUserId (string)

Example:

{"productId":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb","partnerId":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa","customerId":"00000000-0000-0000-0000-000000000001","correlationId":"00000000-0000-0000-0000-000000000002","recordingId":1,"chunkId":1,"isLast":false}
content

string (binary)

Audio chunk binary content (e.g., Opus-encoded audio frame).

Format: Audio codec agnostic (depends on downstream processor).

Note: Can be omitted when chunkId is 1 (first chunk may be metadata-only).

Responses

Name Type Description
200 OK

SuccessResponse

Success - Audio chunk stored and queued for processing.
400 Bad Request

ErrorResponse

Bad Request - Validation failed.

Common causes:

  • Missing metadata or content form field
  • Invalid JSON in metadata
  • Missing required metadata fields
401 Unauthorized

ErrorResponse

Unauthorized - Authentication failed.

Response format depends on failure stage:

  • Missing/invalid token: Plain text response
  • Token not authorized (unrecognized application identity): JSON response with ErrorResponse schema
  • ASP.NET auth challenge: May include WWW-Authenticate header

Action: Verify your S2S token is valid, not expired, and issued for the correct audience/scope.
403 Forbidden

ErrorResponse

Forbidden - Protocol restriction or identity not allowlisted.

Common causes:

  • Using WebSocket/gRPC protocol on the HTTP-only host
  • The issuer/identity from the JWT Bearer token is not allowlisted in the system

Action: Verify you are using the correct host and protocol, and that your token's issuer/identity is allowlisted.
500 Internal Server Error

ErrorResponse

Internal Server Error - Unexpected server-side failure.

Action: Retry with exponential backoff (recommended: 100ms, 500ms, 2.5s, 10s). Contact support if the error persists.

Security

Authorization

Server-to-Server (S2S) machine-to-machine Bearer token (JWT). The recommended identity solution is Microsoft Entra ID, but the service accepts tokens from any identity provider that meets the JWT requirements and has been added to the service's allow list.

Format: Bearer <token>

All REST endpoints require a valid S2S token in the Authorization header. The token must be a JSON Web Token (JWT) whose issuer metadata is publicly available at <issuer>/.well-known/openid-configuration.

Validation flow:

  1. The service validates the JWT signature and standard claims (expiry, audience, issuer).
  2. The service checks the calling application's identity against a configured allow list (M2M inbound policy).
  3. Requests from unrecognized application identities are rejected with 401 Unauthorized.

Contact your Dragon partner relations team to register your identity provider on the allow list.

Type: apiKey
In: header

Definitions

Name Description
ErrorResponse

Standard error response body returned by all endpoints when a request fails.
SuccessResponse

Standard success response body returned by all endpoints when a request succeeds. The error field is always null on success.

ErrorResponse

Object

Standard error response body returned by all endpoints when a request fails.

Name Type Description
error

string

A human-readable error message describing the failure. When multiple validation errors occur, they are concatenated into a single string.

SuccessResponse

Object

Standard success response body returned by all endpoints when a request succeeds. The error field is always null on success.

Name Type Description
error

string

Always null on success. A non-null value indicates the response is an error (see ErrorResponse).