Files

Manage media files for speech services. Upload, import, download, update, and delete files, manage listening audio derivatives, and control file sharing and visibility.

Base path: /api/v1/speech-services/files

Method	Endpoint	Description
GET	/api/v1/speech-services/files	List Files
GET	/api/v1/speech-services/files/shared-with-me	List Shared Files
POST	/api/v1/speech-services/files	Upload File (Multipart)
POST	/api/v1/speech-services/files	Import File from URI
GET	/api/v1/speech-services/files/{id}	Get File
GET	/api/v1/speech-services/files/{id}/content	Download File
PATCH	/api/v1/speech-services/files/{id}	Update File
DELETE	/api/v1/speech-services/files/{id}	Delete File
POST	/api/v1/speech-services/files/{id}/discard-content	Discard Content
GET	/api/v1/speech-services/files/{id}/listening-audio/stream	Stream Listening Audio
POST	/api/v1/speech-services/files/{id}/listening-audio/generate	Generate Listening Audio
DELETE	/api/v1/speech-services/files/{id}/listening-audio	Delete Listening Audio
POST	/api/v1/speech-services/files/{id}/listening-audio/purge	Purge Listening Audio

File Sharing - Base path: /api/v1/speech-services/files/{fileId}/shares

Method	Endpoint	Description
GET	/api/v1/speech-services/files/{fileId}/shares	List Shares
POST	/api/v1/speech-services/files/{fileId}/shares	Share File
DELETE	/api/v1/speech-services/files/{fileId}/shares/{shareId}	Revoke Share

---

List Files

GET /api/v1/speech-services/files

Requires Authentication - Scopes: speech:files:read

Retrieve a paginated list of media files for the authenticated user. Supports filtering by name, filename, SHA-256 checksum, ingestion status, listening audio status, tags, virtual directory path, publish mode, creation date range, and deleted/discarded state.

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	0	Page number (zero-based).
size	integer	No	20	Page size (max 100).
isDeleted	boolean	No	false	Filter by deleted state.
isContentDiscarded	boolean	No	-	Filter by content discarded state.
ingestionStatus	string[]	No	-	Filter by ingestion status (comma-separated). Values: PENDING, PROCESSING, COMPLETED, FAILED.
name	string	No	-	Partial case-insensitive search on file display name.
filename	string	No	-	Partial case-insensitive search on original filename.
sha256	string	No	-	Filter by SHA-256 checksum (exact match).
createdAfter	string (ISO 8601)	No	-	Return files created on or after this timestamp.
createdBefore	string (ISO 8601)	No	-	Return files created on or before this timestamp.
listeningAudio.status	string[]	No	-	Filter by listening audio status (comma-separated). Values: PENDING, PROCESSING, COMPLETED, FAILED.
listeningAudio.deleted	boolean	No	-	Filter by listening audio deleted state.
listeningAudio.contentDiscarded	boolean	No	-	Filter by listening audio content discarded state.
path	string	No	/	Virtual directory path to list. Must start and end with /.
recursive	boolean	No	false	If true, list all descendants recursively. If false, list only direct children.
sort	string	No	creationDate,desc	Sort field and direction. Allowed fields: name, creationDate, size. Direction: asc or desc.
tags	string[]	No	-	Filter by tags (comma-separated display names, case-insensitive).
tagsMatch	string	No	all	Tag match mode: all requires every tag (AND), any requires at least one (OR).
publishMode	string	No	-	Filter by publish mode: PRIVATE or INTERNAL.

cURLPython

curl -X GET "https://koldan.dixilang.com/api/v1/speech-services/files?page=0&size=20&sort=creationDate,desc" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speech-services/files",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"page": 0, "size": 20, "sort": "creationDate,desc"}
)
print(resp.json())

SpeechServiceFilesListResponse

Field	Type	Nullable	Description
files	SpeechServiceFileResponse[]	No	Array of file objects.
directories	string[]	Yes	Subdirectory names under the requested path. Only present when recursive=false.
size	integer	No	Number of items returned in this page.
total	long	No	Total number of matching items across all pages.
filters	object	No	Echo of applied filters.
sort	object	No	Applied sort order (field and direction).

SpeechServiceFilesListResponse

{
  "files": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "meeting-recording",
      "filename": "meeting-2026-02-25.wav",
      "creationDate": "2026-02-25T14:30:00Z",
      ...
    }
  ],
  "directories": ["archived"],
  "size": 1,
  "total": 1
}

Status	Description
200 OK	Files retrieved successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope.
400 Bad Request	Invalid sort field or query parameters.

---

List Shared Files

GET /api/v1/speech-services/files/shared-with-me

Requires Authentication - Scopes: speech:files:read

Retrieve a paginated list of files that other users have shared with the current user, either via direct share or INTERNAL publishing within the same tenant.

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	0	Page number (zero-based).
size	integer	No	20	Page size (max 100).
accessType	string	No	-	Filter by access type: DIRECT_SHARE or INTERNAL. If omitted, returns both.
name	string	No	-	Partial case-insensitive search on file display name.
filename	string	No	-	Partial case-insensitive search on original filename.
sort	string	No	creationDate,desc	Sort field and direction. Allowed fields: name, creationDate, size.

cURLPython

curl -X GET "https://koldan.dixilang.com/api/v1/speech-services/files/shared-with-me?accessType=DIRECT_SHARE" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/speech-services/files/shared-with-me",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"accessType": "DIRECT_SHARE"}
)
print(resp.json())

SpeechServiceSharedFilesListResponse

Field	Type	Nullable	Description
files	SpeechServiceSharedFileResponse[]	No	Array of shared file objects.
size	integer	No	Number of items returned in this page.
total	long	No	Total number of matching items across all pages.
filters	object	No	Echo of applied filters (accessType, name, filename).
sort	object	No	Applied sort order.

SpeechServiceSharedFilesListResponse

{
  "files": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "shared-recording",
      "filename": "interview.wav",
      "accessType": "DIRECT_SHARE",
      "permission": "VIEW",
      ...
    }
  ],
  "size": 1,
  "total": 1
}

Status	Description
200 OK	Shared files retrieved successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope.

---

Upload File

POST /api/v1/speech-services/files

Requires Authentication - Scopes: speech:files:write

Rate Limited - This endpoint enforces stricter rate limits

Upload a new media file via multipart form. A compressed MP3 listening audio derivative is generated by default.

Content Type

This endpoint requires multipart/form-data content type. The file and name parts are required; all other parts are optional.

Multipart Form Parts

Part	Type	Required	Description
file	binary	Yes	The media file to upload.
name	string	Yes	A display name for the file.
description	string	No	A description of the file content.
path	string	No	Virtual directory path. Must start and end with /. Default: /.
metadata	string (JSON)	No	Additional key-value metadata as a JSON string.
tags	string (JSON)	No	Array of tag display names as a JSON string.
generateListeningAudio	boolean	No	Generate a compressed MP3 derivative. Default: true.

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/files \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -F "file=@meeting-2026-02-25.wav" \
  -F "name=meeting-recording" \
  -F "description=Weekly engineering team meeting recording" \
  -F 'path=/meetings/2026/march/' \
  -F 'metadata={"department":"engineering"}' \
  -F 'tags=["Engineering","Meeting"]'

import requests

with open("meeting-2026-02-25.wav", "rb") as f:
    resp = requests.post(
        "https://koldan.dixilang.com/api/v1/speech-services/files",
        headers={"Authorization": f"Bearer {JWT}"},
        files={"file": ("meeting-2026-02-25.wav", f)},
        data={
            "name": "meeting-recording",
            "description": "Weekly engineering team meeting recording",
            "path": "/meetings/2026/march/",
            "metadata": '{"department":"engineering"}',
            "tags": '["Engineering","Meeting"]'
        }
    )
print(resp.json())

SpeechServiceFileResponse

Returns the created file object. See Data Types for the full response schema.

Status	Description
201 Created	File uploaded successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope.
400 Bad Request	Invalid metadata JSON, tags JSON, or missing required parts.
429 Too Many Requests	Rate limit exceeded.

---

Import File from URI

POST /api/v1/speech-services/files

Requires Authentication - Scopes: speech:files:write

Rate Limited - This endpoint enforces stricter rate limits

Import a file from a remote URI (HTTP, HTTPS, or S3). Ingestion is performed asynchronously - the file's ingestionStatus starts as PENDING and transitions through PROCESSING to COMPLETED or FAILED.

Content Type

This endpoint requires application/json content type. Both endpoints share the same POST /api/v1/speech-services/files path - the server distinguishes them by the Content-Type header.

SpeechServiceFileUriImportRequest

Field	Type	Required	Description
uri	string	Yes	The URI of the file to import (HTTP, HTTPS, or S3).
name	string	Yes	A display name for the file.
description	string	No	A description of the file content.
path	string	No	Virtual directory path. Must start and end with /. Default: /.
metadata	object	No	Additional key-value metadata associated with the file.
generateListeningAudio	boolean	No	Generate a compressed MP3 derivative after ingestion. Default: true.

SpeechServiceFileUriImportRequest

{
  "uri": "https://storage.example.com/recordings/meeting.wav",
  "name": "meeting-recording",
  "description": "Weekly engineering team meeting recording",
  "path": "/meetings/2026/march/",
  "metadata": {"department": "engineering"},
  "generateListeningAudio": true
}

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/files \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://storage.example.com/recordings/meeting.wav",
    "name": "meeting-recording",
    "description": "Weekly engineering team meeting recording",
    "path": "/meetings/2026/march/",
    "metadata": {"department": "engineering"},
    "generateListeningAudio": true
  }'

import requests

resp = requests.post(
    "https://koldan.dixilang.com/api/v1/speech-services/files",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type": "application/json"
    },
    json={
        "uri": "https://storage.example.com/recordings/meeting.wav",
        "name": "meeting-recording",
        "description": "Weekly engineering team meeting recording",
        "path": "/meetings/2026/march/",
        "metadata": {"department": "engineering"},
        "generateListeningAudio": True
    }
)
print(resp.json())

SpeechServiceFileResponse

Returns the created file object with ingestionStatus set to PENDING. See Data Types for the full response schema.

Status	Description
201 Created	Import initiated successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope.
400 Bad Request	Invalid request body.
429 Too Many Requests	Rate limit exceeded.

---

Get File

GET /api/v1/speech-services/files/{id}

Requires Authentication - Scopes: speech:files:read

Retrieve metadata for a single media file by its unique identifier.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

SpeechServiceFileResponse

Returns the file metadata object. See Data Types for the full response schema.

Status	Description
200 OK	File metadata retrieved successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized to access this file.
404 Not Found	File not found.

---

Download File

GET /api/v1/speech-services/files/{id}/content

Requires Authentication - Scopes: speech:files:read

Bandwidth Throttled – This endpoint enforces stricter bandwidth limitations

Download the binary content of a media file. The response is the raw file bytes with application/octet-stream content type. Download transfer speed is throttled according to your effective speechServiceFileDownloadBytesPerSecond rate limit.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/content \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -o downloaded-file.wav

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/content",
    headers={"Authorization": f"Bearer {JWT}"},
    stream=True
)
with open("downloaded-file.wav", "wb") as f:
    for chunk in resp.iter_content(chunk_size=8192):
        f.write(chunk)

Response

Returns the raw file bytes as application/octet-stream with Content-Disposition: attachment header.

Status	Description
200 OK	File content returned.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized to access this file.
404 Not Found	File not found.
410 Gone	File has been deleted or content has been discarded.
422 Unprocessable Entity	File ingestion is not completed (URI imports).

---

Update File

PATCH /api/v1/speech-services/files/{id}

Requires Authentication - Scopes: speech:files:write

Update the metadata of an existing media file. Only provided fields are updated - omitted fields remain unchanged.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file to update.

SpeechServiceFileUpdateRequest

Field	Type	Required	Description
name	string	No	Updated display name.
description	string	No	Updated description.
path	string	No	Updated virtual directory path. Must start and end with /.
metadata	object	No	Updated key-value metadata (replaces entire metadata object).
tags	string[]	No	Updated list of tag display names. Replace semantics: the provided list becomes the complete tag set. Pass an empty array to clear all tags. Omit to leave unchanged.
publishMode	string	No	Publish mode: PRIVATE (owner + shared users only) or INTERNAL (all tenant users).

SpeechServiceFileUpdateRequest

{
  "name": "meeting-recording-updated",
  "description": "Updated description for meeting recording",
  "path": "/meetings/archived/",
  "tags": ["Engineering", "Archived"],
  "publishMode": "INTERNAL"
}

cURLPython

curl -X PATCH https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "meeting-recording-updated",
    "tags": ["Engineering", "Archived"],
    "publishMode": "INTERNAL"
  }'

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.patch(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type": "application/json"
    },
    json={
        "name": "meeting-recording-updated",
        "tags": ["Engineering", "Archived"],
        "publishMode": "INTERNAL"
    }
)
print(resp.json())

SpeechServiceFileResponse

Returns the updated file object. See Data Types for the full response schema.

Status	Description
200 OK	File updated successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized to modify this file.
400 Bad Request	Invalid request body or tag names.
404 Not Found	File not found.

---

Delete File

DELETE /api/v1/speech-services/files/{id}

Requires Authentication - Scopes: speech:files:delete

Delete a file and all associated data. Use ?purge=true for immediate permanent removal of the file and its binary content from storage.

Purge is Irreversible

When purge=true, the file's binary content and listening audio are permanently deleted from storage and cannot be recovered.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

Query Parameters

Parameter	Type	Required	Default	Description
purge	boolean	No	false	Immediately purge all data (binary content + listening audio) from storage.

cURLPython

curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.delete(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Status	Description
204 No Content	File deleted (or purged) successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized to delete this file.
404 Not Found	File not found.
409 Conflict	File is already deleted (when purge=false).

---

Discard Content

POST /api/v1/speech-services/files/{id}/discard-content

Requires Authentication - Scopes: speech:files:write

Remove the binary content of a file to free storage space. File metadata, tags, shares, and associated data remain accessible. This operation is irreversible.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/discard-content \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.post(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/discard-content",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Status	Description
204 No Content	File content discarded successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized.
409 Conflict	File is deleted or content is already discarded.

---

Stream Listening Audio

GET /api/v1/speech-services/files/{id}/listening-audio/stream

Requires Authentication - Scopes: speech:files:read

Bandwidth Throttled – This endpoint enforces stricter bandwidth limitations

Stream the listening audio MP3 derivative with HTTP Range support for buffered playback. When no Range header is provided, the full file is returned. Download transfer speed is throttled according to your effective speechServiceFileDownloadBytesPerSecond rate limit.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

Request Headers

Header	Required	Description
Range	No	Byte range for partial content (e.g., bytes=0-1048575).

cURLPython

# Full download
curl -X GET https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/listening-audio/stream \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -o listening.mp3

# Range request (first 1 MB)
curl -X GET https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/listening-audio/stream \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Range: bytes=0-1048575" \
  -o listening-part.mp3

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Full download
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/listening-audio/stream",
    headers={"Authorization": f"Bearer {JWT}"},
    stream=True
)
with open("listening.mp3", "wb") as f:
    for chunk in resp.iter_content(chunk_size=8192):
        f.write(chunk)

# Range request (first 1 MB)
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/listening-audio/stream",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Range": "bytes=0-1048575"
    },
    stream=True
)

Response

Returns audio/mpeg content with Accept-Ranges: bytes header.

Status	Description
200 OK	Full audio content returned.
206 Partial Content	Byte range returned. Includes Content-Range header.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized.
410 Gone	File is deleted, listening audio is deleted, or listening audio content has been discarded.
416 Range Not Satisfiable	Requested range is invalid or out of bounds.
422 Unprocessable Entity	Listening audio is not ready (status is not COMPLETED).

---

Generate Listening Audio

POST /api/v1/speech-services/files/{id}/listening-audio/generate

Requires Authentication - Scopes: speech:files:write

Trigger listening audio generation for a file that does not yet have listening audio, or retry after a failed attempt. The generation is asynchronous - the listeningAudio.status transitions from PENDING through PROCESSING to COMPLETED or FAILED.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/listening-audio/generate \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.post(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/listening-audio/generate",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

SpeechServiceFileResponse

Returns the file object with listeningAudio.status set to PENDING. See Data Types for the full response schema.

Status	Description
202 Accepted	Generation triggered successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized.
404 Not Found	File not found or has been deleted.
409 Conflict	Listening audio already exists, is in progress, or has been deleted/purged.
410 Gone	File content has been discarded - source binary is no longer available.
422 Unprocessable Entity	File ingestion is not completed (URI imports).

---

Delete Listening Audio

DELETE /api/v1/speech-services/files/{id}/listening-audio

Requires Authentication - Scopes: speech:files:delete

Delete the listening audio of a file. Use ?purge=true for immediate permanent removal of the listening audio content from storage.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

Query Parameters

Parameter	Type	Required	Default	Description
purge	boolean	No	false	Immediately purge listening audio content from storage.

cURLPython

curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/listening-audio \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.delete(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/listening-audio",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Status	Description
204 No Content	Listening audio deleted (or purged) successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized.
404 Not Found	File not found or does not have listening audio.
409 Conflict	Listening audio is already deleted (when purge=false).

---

Purge Listening Audio

POST /api/v1/speech-services/files/{id}/listening-audio/purge

Requires Authentication - Scopes: speech:files:write

Permanently remove the listening audio binary content to free storage. The listening audio metadata remains on the file record. This operation is irreversible.

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the file.

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/listening-audio/purge \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.post(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/listening-audio/purge",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Status	Description
204 No Content	Listening audio content purged successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized.
404 Not Found	File not found or does not have listening audio.
409 Conflict	Listening audio is not completed, is deleted, or is already purged.

---

List Shares

GET /api/v1/speech-services/files/{fileId}/shares

Requires Authentication - Scopes: speech:files:read

Retrieve all direct user shares for a file. Only the file owner can list shares.

Path Parameters

Parameter	Type	Required	Description
fileId	string (UUID)	Yes	Unique identifier of the file.

cURLPython

curl -X GET https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/shares \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/shares",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())

SpeechServiceFileShareListResponse

Field	Type	Nullable	Description
shares	SpeechServiceFileShareResponse[]	No	Array of share objects.

SpeechServiceFileShareListResponse

{
  "shares": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "userId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "permission": "VIEW",
      "createdAt": "2026-04-02T10:00:00Z"
    }
  ]
}

Status	Description
200 OK	Shares retrieved successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized (not the file owner).
404 Not Found	File not found.

---

Share File

POST /api/v1/speech-services/files/{fileId}/shares

Requires Authentication - Scopes: speech:files:share

Grant a user access to a file with VIEW or EDIT permission. If a share already exists for the target user, the permission is updated (returns 200). Otherwise a new share is created (returns 201). The target user must belong to the same tenant.

Path Parameters

Parameter	Type	Required	Description
fileId	string (UUID)	Yes	Unique identifier of the file.

SpeechServiceFileShareRequest

Field	Type	Required	Description
userId	string (UUID)	Yes	UUID of the user to share with.
permission	string	No	Permission level: VIEW (read-only) or EDIT (read + write). Default: VIEW.

SpeechServiceFileShareRequest

{
  "userId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "permission": "VIEW"
}

cURLPython

curl -X POST https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/shares \
  -H "X-API-Key: $KOLDAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "permission": "VIEW"
  }'

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.post(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/shares",
    headers={
        "Authorization": f"Bearer {JWT}",
        "Content-Type": "application/json"
    },
    json={
        "userId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "permission": "VIEW"
    }
)
print(resp.json())

SpeechServiceFileShareResponse

Field	Type	Nullable	Description
id	string (UUID)	No	Unique identifier of this share.
fileId	string (UUID)	No	UUID of the file being shared.
userId	string (UUID)	No	UUID of the user this file is shared with.
permission	string	No	Permission level: VIEW or EDIT.
createdBy	string (UUID)	No	UUID of the user who created this share (file owner).
createdAt	string (ISO 8601)	No	Timestamp when this share was created.

Status	Description
201 Created	Share created.
200 OK	Existing share updated with new permission.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized (not the file owner).
400 Bad Request	Cannot share with yourself or target user not found.
404 Not Found	File not found.

---

Revoke Share

DELETE /api/v1/speech-services/files/{fileId}/shares/{shareId}

Requires Authentication - Scopes: speech:files:share

Remove a direct share, revoking the user's access to the file. Only the file owner can revoke shares.

Path Parameters

Parameter	Type	Required	Description
fileId	string (UUID)	Yes	Unique identifier of the file.
shareId	string (UUID)	Yes	Unique identifier of the share to revoke.

cURLPython

curl -X DELETE https://koldan.dixilang.com/api/v1/speech-services/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/shares/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
share_id = "c3d4e5f6-a7b8-9012-cdef-123456789012"
resp = requests.delete(
    f"https://koldan.dixilang.com/api/v1/speech-services/files/{file_id}/shares/{share_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.status_code)  # 204

Response

No response body.

Status	Description
204 No Content	Share revoked successfully.
401 Unauthorized	Missing or invalid authentication.
403 Forbidden	Insufficient scope or not authorized (not the file owner).
404 Not Found	File or share not found.

---

Data Types

SpeechServiceFileResponse

Field	Type	Nullable	Description
id	string (UUID)	No	Unique identifier of the file.
name	string	No	Display name of the file.
filename	string	Yes	Original filename of the uploaded file.
description	string	Yes	Description of the file content.
path	string	No	Virtual directory path (S3-key style). Always starts and ends with /.
size	long	Yes	File size in bytes.
durationSeconds	double	Yes	Duration of the media file in seconds.
sha256	string	Yes	SHA-256 checksum (lowercase hex, 64 characters).
ingestionStatus	string	Yes	Ingestion status for URI-imported files: PENDING, PROCESSING, COMPLETED, FAILED. null for directly uploaded files.
listeningAudio	ListeningAudioResponse	Yes	Listening audio sub-object. null if listening audio was never requested.
isDeleted	boolean	No	Whether the file has been deleted.
isPurged	boolean	No	Whether the file's binary data has been permanently removed.
isContentDiscarded	boolean	No	Whether the file content has been discarded.
creationDate	string (ISO 8601)	No	Timestamp when the file was created.
deletedAt	string (ISO 8601)	Yes	Timestamp when the file was deleted.
purgedAt	string (ISO 8601)	Yes	Timestamp when the file's binary data was purged.
purgeAt	string (ISO 8601)	Yes	Scheduled timestamp for automatic purge.
contentDiscardedAt	string (ISO 8601)	Yes	Timestamp when the file content was discarded.
metadata	object	Yes	Additional key-value metadata associated with the file.
tags	string[]	Yes	Tag display names assigned to this file, sorted alphabetically.
publishMode	string	Yes	Publish mode: PRIVATE or INTERNAL.
publishedAt	string (ISO 8601)	Yes	Timestamp when the file was first published.

ListeningAudioResponse

Field	Type	Nullable	Description
status	string	No	Generation status: PENDING, PROCESSING, COMPLETED, FAILED.
size	long	Yes	Size of the generated MP3 in bytes.
createdAt	string (ISO 8601)	Yes	Timestamp when the MP3 generation completed.
deleted	boolean	No	Whether the listening audio has been deleted.
isPurged	boolean	No	Whether the listening audio content has been discarded (purged).
deletedAt	string (ISO 8601)	Yes	Timestamp when the listening audio was deleted.
purgedAt	string (ISO 8601)	Yes	Timestamp when the listening audio content was discarded.
purgeAt	string (ISO 8601)	Yes	Scheduled timestamp for automatic purge.

SpeechServiceSharedFileResponse

Extends SpeechServiceFileResponse with additional sharing context fields:

Field	Type	Nullable	Description
accessType	string	No	How the current user gained access: DIRECT_SHARE or INTERNAL.
permission	string	Yes	Permission level: VIEW or EDIT. Only present for DIRECT_SHARE access.
sharedBy	string (UUID)	Yes	UUID of the user who shared this file. Only present for DIRECT_SHARE access.
sharedAt	string (ISO 8601)	Yes	Timestamp when the share was created. Only present for DIRECT_SHARE access.

SpeechServiceFileShareResponse

Field	Type	Nullable	Description
id	string (UUID)	No	Unique identifier of this share.
fileId	string (UUID)	No	UUID of the file being shared.
userId	string (UUID)	No	UUID of the user this file is shared with.
permission	string	No	Permission level: VIEW or EDIT.
createdBy	string (UUID)	No	UUID of the user who created this share (file owner).
createdAt	string (ISO 8601)	No	Timestamp when this share was created.

---

Enumerations

SpeechServiceFilePublishMode

Value	Description
PRIVATE	Visible only to the owner and explicitly shared users.
INTERNAL	Visible to all authenticated users within the same tenant.

SpeechServiceFileAccessType

Value	Description
DIRECT_SHARE	Access granted via a direct user-to-user share.
INTERNAL	Access granted because the file is published INTERNAL within the same tenant.

SpeechServiceFileSharePermission

Value	Description
VIEW	Read-only access: download, stream, and view metadata.
EDIT	Read and write access: update metadata.

IngestionStatus

Value	Description
PENDING	Import has been accepted but processing has not started.
PROCESSING	File is being downloaded and ingested.
COMPLETED	Ingestion finished successfully. The file is ready.
FAILED	Ingestion failed. Check the file for error details.

ListeningAudioStatus

Value	Description
PENDING	Generation has been triggered but processing has not started.
PROCESSING	MP3 derivative is being generated.
COMPLETED	Listening audio is ready for streaming.
FAILED	Generation failed. You may retry via Generate Listening Audio.

---

File Lifecycle

Files follow a lifecycle: active → deleted → purged. Deleted files retain their metadata, while purged files have their binary content permanently removed from storage. You can also discard content independently to free storage while keeping metadata intact.

Listening Audio

Listening audio is a compressed MP3 derivative automatically generated from uploaded media files. It enables lightweight streaming playback without downloading the full original file. Listening audio has its own independent lifecycle (delete, purge) separate from the parent file.