Overview and Examples
The MiRTA PBX OpenAPI endpoint exposes configuration and reporting APIs as an OpenAPI 3.0.3 JSON specification. OpenAPI describes the available paths, methods, authentication schemes, request bodies, and response schemas in a machine-readable format.
Using the OpenAPI specification makes integrations easier to test and maintain: developers can generate client code, import the API into tools such as Postman or Swagger UI, validate request shapes, and keep documentation aligned with the endpoint implementation.
Base URL
https://pbx.example.com/pbx/openapi.php
https://pbx.example.com/pbx/openapi.php?spec=1
https://pbx.example.com/pbx/openapi.php/openapi.json
https://pbx.example.com/pbx/openapi.php/swagger.jsonAuthentication
Send the API key as a key query parameter, an X-API-Key header, or an Authorization: Bearer token. Tenant API keys require a tenant parameter. Global keys can access global administration objects and can list tenant-scoped objects across tenants when no tenant parameter is supplied.
curl -H "X-API-Key: TENANT_API_KEY" \
"https://pbx.example.com/pbx/openapi.php/extensions?tenant=CANISTRACCI"
curl -H "Authorization: Bearer TENANT_API_KEY" \
"https://pbx.example.com/pbx/openapi.php/extensions/number/100?tenant=CANISTRACCI"
curl "https://pbx.example.com/pbx/openapi.php/extensions?tenant=CANISTRACCI&key=TENANT_API_KEY"Endpoint Patterns
| Action | Pattern |
|---|---|
| List | GET https://pbx.example.com/pbx/openapi.php/extensions?tenant=CANISTRACCI |
| Get by ID | GET https://pbx.example.com/pbx/openapi.php/extensions/EXTENSION_ID?tenant=CANISTRACCI |
| Get extension by number | GET https://pbx.example.com/pbx/openapi.php/extensions/number/100?tenant=CANISTRACCI |
| Get live extension state | GET https://pbx.example.com/pbx/openapi.php/extensions/state?tenant=CANISTRACCI&number=100 |
| Dial | POST https://pbx.example.com/pbx/openapi.php/dial?tenant=CANISTRACCI |
| Transfer live call | POST https://pbx.example.com/pbx/openapi.php/calls/transfer?tenant=CANISTRACCI |
| Queue agent action | POST https://pbx.example.com/pbx/openapi.php/queues/QUEUE_ID/agents/EXTENSION_ID/{login|logout|pause|unpause}?tenant=CANISTRACCI |
| Create | POST https://pbx.example.com/pbx/openapi.php/extensions?tenant=CANISTRACCI |
| Modify | PATCH https://pbx.example.com/pbx/openapi.php/extensions/EXTENSION_ID?tenant=CANISTRACCI |
| Delete | DELETE https://pbx.example.com/pbx/openapi.php/extensions/EXTENSION_ID?tenant=CANISTRACCI |
Supported Objects
Each supported object has its own page in this chapter. Most configuration objects support CRUD operations. CDR, Simple CDR, AI Analysis, and AI Logs are read-only reporting endpoints. The examples use fictional IDs, numbers, names, and keys; replace them with values from the target PBX.
| Object | Primary path | Authentication scope | Operations or required fields |
|---|---|---|---|
| Auth Token | /auth/token | Global full API key | POST generate, DELETE reset |
| Dial | /dial | Tenant full API key | POST only; requires source and dest |
| Live Call Transfer | /calls/transfer | Writable full tenant or global API key; exact tenant required | POST blind or attended transfer of an active tenant-owned channel |
| CDR | /cdrs | Tenant API key or global key; GET only | GET only |
| Simple CDR | /simplecdrs | Tenant API key or global key; GET only | GET only |
| AI Analysis | /aianalysis | Tenant API key or global key; GET only | GET only; requires uniqueid |
| AI Logs | /ailogs | Tenant full or read-only API key, or global key; GET only | GET only; JSON or CSV; defaults to the current day |
| Extension | /extensions | Tenant API key | number or ex_number; GET /extensions/state for live state |
| Tenant | /tenants | Global API key | te_name, te_code |
| User | /users | Global API key | us_username |
| User Profile | /userprofiles | Global API key | up_name |
| Routing Profile | /routingprofiles | Global API key | rp_name |
| Provider | /providers | Global API key | pr_name |
| Voicemail | /voicemails | Tenant API key | mailbox |
| IVR | /ivrs | Tenant API key | iv_name |
| Custom Destination | /customdestinations | Tenant API key or global key with global=1 | cu_name, cu_ct_id |
| Condition | /conditions | Tenant API key | co_type |
| Hunt List | /huntlists | Tenant API key | hu_name |
| DID | /dids | Tenant API key | di_number |
| Queue | /queues | Tenant API key; agent actions require a writable full key and an exact tenant | CRUD; GET /queues/{id}/state for live state; POST /queues/{queueId}/agents/{agentId}/{login|logout|pause|unpause} for agent actions |
| Setting | /settings | Tenant API key or global key with global=1 | se_code |
| Media File | /mediafiles; /mediafiles/{id}/download | Tenant or global key for metadata; full key required to download audio | me_name; binary download examples |
| Music On Hold | /musiconholds | Tenant API key or global key with global=1 | mu_name |
| Paging Group | /paginggroups | Tenant API key | pa_name, pa_number |
| Conference Room | /conferencerooms | Tenant API key | cr_name, cr_number |
| Flow | /flows | Tenant API key | fl_name |
| Tenant Variable | /tenantvariables | Tenant API key | tv_al_id |
| DISA | /disas | Tenant API key | ds_name |
| Caller ID Blacklist | /calleridblacklists | Tenant API key or global key with global=1 | bl_callerid |
| Campaign | /campaigns | Tenant API key | ca_name |
| Campaign Number | /campaignnumbers | Tenant API key | cn_ca_id, cn_number |
| Cron Job | /cronjobs | Tenant API key or global key with global=1 | cr_name |
| Feature Code | /featurecodes | Tenant API key or global key with global=1 | fe_code |
| Short Number | /shortnumbers | Tenant API key or global key with global=1 | sn_number |
| Phone Book | /phonebooks | Tenant API key | pb_name |
| Phone Book Entry | /phonebookentries | Tenant API key | phonebook_id, at least one value |
| Provisioning Phone | /provisioningphones | Tenant API key | ph_name, ph_mac |
Errors
Errors are returned as JSON with an error code and message. Common errors include missing_api_key, invalid_api_key, tenant_not_found, invalid_json, missing_required_field, read_only_api_key, method_not_allowed, and not_found.
Phone book collection operations
The /phonebooks/{id}/entries endpoint supports downloading all stored contacts (GET), adding 1–500 contacts in an atomic batch (POST), and clearing only the selected phone book (DELETE). A tenant must be selected. Read-only keys can download; writes require a full key. See Phone Book for examples.
Configuration API additions (1.2.0)
Thirty additional resources cover Configuration/Settings and child records, with full create/read/update/delete operations. Extension technology conversion and voicemail messages/greetings now have dedicated endpoints. The generated internal directory is read-only; its source configuration objects remain editable.
See Additional Configuration Operations for complete request fields, scope rules and examples.
Media File Downloads
GET /mediafiles/{id}/download?tenant=TENANTCODE returns the original audio file as a binary attachment. It requires a full tenant or global API key; read-only keys cannot download audio. Tenant scoping is enforced. Global full keys can use global=yes for shared media. List/detail media endpoints return metadata only, and download errors remain JSON. See Media File: Download a Media File for curl examples, response headers, storage support and errors.