Audio Upload - Finalize Upload

Service:: Dragon Copilot APIs

API Version:: 2025-07-15

Signals that all audio chunks for a recording have been uploaded and triggers processing.
Signal that all audio chunks for a recording have been uploaded and trigger processing of the complete recording.

Prerequisites:

An ambient session must exist for the given correlationId (created via the Dragon Copilot Partner API PUT /ambient-sessions). See Create Ambient Session.
Audio chunks must be uploaded via PUT /audio/storeChunk for the same correlationId and recordingId.

Note: Audio chunks and the finalize call can arrive in any order. The service reconciles chunks as they arrive and completes processing once all declared chunks have been received. The totalChunks must match the number of chunks uploaded.

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

POST https://ambient-audio-service.copilot.us.dragon.com/audio/finalizeUpload?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

Name Required Type Description

Authorization

True

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: The service validates the JWT signature and standard claims (expiry, audience, issuer). The service checks the calling application's identity against a configured allow list (M2M inbound policy). 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.

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:

The service validates the JWT signature and standard claims (expiry, audience, issuer).
The service checks the calling application's identity against a configured allow list (M2M inbound policy).
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

Name	Required	Type	Description
correlationId	True	string	Session/correlation identifier that ties this finalize request to the ambient session and previously uploaded audio chunks.
customerId	True	string (uuid)	Unique identifier for the customer (healthcare organization) that owns the audio data. Assigned during partner onboarding.
partnerId	True	string (uuid)	Unique identifier for the partner organization. Assigned during partner onboarding.
productId	True	string (uuid)	Unique identifier for the product associated with this audio upload. Assigned during partner onboarding.
recordingId	True	integer (int32) minimum: 1	Sequential recording number within the ambient session. Must match the recording ID used during chunk uploads. Validation: Must be a positive integer (> 0).
totalChunks	True	integer (int32) minimum: 1	Total number of audio chunks uploaded for this recording. Must match the number of chunks sent via `/audio/storeChunk`. Validation: Must be a positive integer (> 0).
ehrInstanceId		string	Identifier of the Electronic Health Record (EHR) instance. Optional - used when the customer operates multiple EHR instances.
externalUserId		string	External user identifier for the clinician or provider associated with this audio session. Optional.
skipAmbientSessionExistence		boolean	If true, skip the ambient session existence check. Defaults to `false`.

Responses

Name	Type	Description
200 OK	SuccessResponse	Success - Finalize upload request accepted and queued for processing.
400 Bad Request	ErrorResponse	Bad Request - Validation failed. Validation rules: `productId` is required (valid UUID) `partnerId` is required (valid UUID) `customerId` is required (valid UUID) `correlationId` is required (non-empty string) `recordingId` must be a positive integer (> 0) `totalChunks` must be a positive integer (> 0)
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.
404 Not Found	ErrorResponse	Not Found - Ambient session not found for the given `correlationId`. Returned only when ambient session checks are enforced.
500 Internal Server Error	ErrorResponse	Internal Server Error - Unexpected server-side failure. Action: Retry with exponential backoff. Contact support if persists.

Security

Authorization

Format: Bearer <token>

Validation flow:

The service validates the JWT signature and standard claims (expiry, audience, issuer).
The service checks the calling application's identity against a configured allow list (M2M inbound policy).
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
AudioFinalizeUploadMetadata	Audio Finalize Upload Metadata
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.

AudioFinalizeUploadMetadata

Object

Audio Finalize Upload Metadata

Name	Type	Default value	Description
correlationId	string		Session/correlation identifier that ties this finalize request to the ambient session and previously uploaded audio chunks.
customerId	string (uuid)		Unique identifier for the customer (healthcare organization) that owns the audio data. Assigned during partner onboarding.
ehrInstanceId	string		Identifier of the Electronic Health Record (EHR) instance. Optional - used when the customer operates multiple EHR instances.
externalUserId	string		External user identifier for the clinician or provider associated with this audio session. Optional.
partnerId	string (uuid)		Unique identifier for the partner organization. Assigned during partner onboarding.
productId	string (uuid)		Unique identifier for the product associated with this audio upload. Assigned during partner onboarding.
recordingId	integer (int32) minimum: 1		Sequential recording number within the ambient session. Must match the recording ID used during chunk uploads. Validation: Must be a positive integer (> 0).
skipAmbientSessionExistence	boolean	False	If true, skip the ambient session existence check. Defaults to `false`.
totalChunks	integer (int32) minimum: 1		Total number of audio chunks uploaded for this recording. Must match the number of chunks sent via `/audio/storeChunk`. Validation: Must be a positive integer (> 0).

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).