Media File

The Media File object is supported by the MiRTA PBX OpenAPI endpoint. This object is normally tenant-scoped. With a global API key, use global=1 to manage the shared/global record set. Tenant writes still require tenant=CANISTRACCI.

Object Summary

Property	Value
Object	mediafile
Primary path	/mediafiles
ID field	me_id
Label field	me_name
Primary source table	me_mediafiles
Required on create	me_name
Path aliases	/mediafiles, /media_files, /media_file

Endpoint Patterns

Action	Example pattern
List	GET https://pbx.example.com/pbx/openapi.php/mediafiles?tenant=CANISTRACCI
Get by ID	GET https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID?tenant=CANISTRACCI
Download file	GET https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID/download?tenant=CANISTRACCI (full API key)
Create	POST https://pbx.example.com/pbx/openapi.php/mediafiles?tenant=CANISTRACCI
Update	PATCH https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID?tenant=CANISTRACCI
Delete	DELETE https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID?tenant=CANISTRACCI

Accepted Field Aliases

Request field	Source field
name	me_name
description	me_description
format	me_format
type	me_type
text	me_text
engine	me_engine
language	me_language
data_base64	me_data

Examples

List Media Files

Returns the media files visible to the key and scope.

curl -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/mediafiles?tenant=CANISTRACCI"

Get Media File

Reads metadata by its internal ID. List and detail responses omit me_data and do not contain audio, even when using a global full API key. Use the download endpoint to retrieve the file.

curl -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID?tenant=CANISTRACCI"

Create Media File

Creates a new object. Use the short aliases shown above or the source field names.

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs API Welcome Prompt",
  "description": "Generated prompt for documentation",
  "type": "tts",
  "text": "Welcome to Kartoon Cars. Press 1 for sales or 2 for support.",
  "engine": "azure",
  "language": "en-US"
}' \
  "https://pbx.example.com/pbx/openapi.php/mediafiles?tenant=CANISTRACCI"

Edit Media File

Updates only the supplied fields.

curl -X PATCH \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Updated generated prompt"
}' \
  "https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID?tenant=CANISTRACCI"

Delete Media File

Deletes the object. Check references before deleting configuration used by routing or reporting.

curl -X DELETE \
  -H "X-API-Key: TENANT_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/mediafiles/OBJECT_ID?tenant=CANISTRACCI"

List Global Media Files

Uses the shared/global record set for object types that support global rows.

curl -H "X-API-Key: GLOBAL_API_KEY" \
  "https://pbx.example.com/pbx/openapi.php/mediafiles?global=1"

Media File Binary Upload

Sends audio data as base64. Replace the shortened example with the complete encoded file.

curl -X POST \
  -H "X-API-Key: TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Docs API Uploaded Prompt",
  "format": "wav",
  "data_base64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."
}' \
  "https://pbx.example.com/pbx/openapi.php/mediafiles?tenant=CANISTRACCI"

Download a Media File

GET /mediafiles/{id}/download?tenant=TENANTCODE returns the original stored file as an attachment. Use the positive me_id returned by the media list. The audio is returned as binary bytes, without base64 encoding or transcoding.

A full API key is required. Tenant full keys can download only their own tenant's media files and must supply tenant. Read-only keys receive HTTP 403, with error code full_api_key_required. A global full key can select a tenant or omit tenant to download a media file by ID across tenants. For shared/global media, use global=yes with a global full key.

Download Tenant Media

curl --fail --show-error \
  -H 'X-API-Key: TENANT_API_KEY' \
  --output /tmp/media.wav \
  'https://pbx.example.com/pbx/openapi.php/mediafiles/123/download?tenant=CANISTRACCI'

Replace 123 with the media file ID. The example writes WAV bytes to /tmp/media.wav; choose a filename matching the stored format when downloading MP3, GSM or another format. The server does not convert the audio based on the output filename.

Download Global Media

curl --fail --show-error \
  -H 'X-API-Key: GLOBAL_API_KEY' \
  --output /tmp/global-media.wav \
  'https://pbx.example.com/pbx/openapi.php/mediafiles/123/download?global=yes'

Download Response and Storage

• Content-Disposition: attachment supplies a filename derived from the media name and stored extension.
• Content-Type reflects the stored format, such as audio/wav, audio/mpeg or audio/gsm. Other formats may use application/octet-stream.
• Content-Length reports the actual file size. Successful responses contain file bytes; failures remain JSON.
• Database, filesystem, FTP, SSL-FTP, SFTP and S3 storage are supported. The storage lookup uses the media file's actual tenant owner and the system media-storage settings when inherited.

The singular alias /mediafile/123/download is also accepted. The equivalent query form is openapi.php?object=mediafile&action=download&id=123&tenant=CANISTRACCI. Downloads support GET only.

HTTP status	Meaning
400	Invalid or missing media ID.
401 / 403	Missing/invalid key, read-only key, denied IP address or insufficient scope.
404	Media record is outside the selected scope, does not exist, or has no stored audio.
405	A method other than GET was used.
409	The stored media format is unavailable.
500 / 502 / 503	Database, storage retrieval or configuration failure. Errors are JSON; no file download starts.

Common Errors

Error	Meaning
missing_api_key	No API key was supplied in the query string, X-API-Key, or bearer token.
invalid_api_key	The supplied key does not match the tenant or global API key.
tenant_required	A tenant code is required for tenant-scoped writes or tenant-key reads.
read_only_api_key	The key can read data but cannot create, update, or delete objects.
missing_required_field	A required create field is missing.