OpenAPI

From MiRTA PBX documentation
Revision as of 08:06, 25 May 2026 by Admin (talk | contribs)
Jump to navigation Jump to search

Overview

openapi.php is the JSON API endpoint based on the OpenAPI specification.

The API uses the existing API keys:

  • Full API key: APIKEY
  • Read-only API key: READONLYAPIKEY

Both global and tenant-level keys are supported.

The implemented API object is extension. It provides endpoints for listing extensions and retrieving detailed information for a single extension.

OpenAPI Specification

The OpenAPI specification is available from: 

openapi.php
openapi.php?spec=1
openapi.php/openapi.json
openapi.php/swagger.json

The response is an OpenAPI 3.0.3 JSON document.

Authentication

The API key can be provided in any of these ways.

Query Parameter

openapi.php/extensions?tenant=TENANTCODE&key=APIKEY

X-API-Key: APIKEY

Bearer Token

Authorization: Bearer APIKEY

API Key Scope

Tenant API Key

When using a tenant-level API key, the tenant parameter is required. 

openapi.php/extensions?tenant=TENANTCODE&key=TENANT_API_KEY

Global API Key

When using a global API key, tenant is optional.

If tenant is provided, only that tenant's extensions are returned.

If tenant is omitted, extensions from all tenants are returned. 

openapi.php/extensions?key=GLOBAL_API_KEY

List Extensions

Endpoint

GET openapi.php/extensions

Alternative compatibility format: 

openapi.php?object=extension&action=list

Parameters

Name Required Description
key Yes, unless using header authentication Full or read-only API key
tenant Required for tenant keys Tenant code or tenant name

Example Request

curl "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE&key=APIKEY"

Using header authentication: 

curl \
  -H "X-API-Key: APIKEY" \
  "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"

Using bearer authentication: 

curl \
  -H "Authorization: Bearer APIKEY" \
  "https://pbx.example.com/openapi.php/extensions?tenant=TENANTCODE"

Example Response

[
  {
    "id": 101,
    "number": "100",
    "name": "Reception",
    "tech": "PJSIP"
  },
  {
    "id": 102,
    "number": "101",
    "name": "Office",
    "tech": "SIP"
  }
]

Response Fields

Field Type Description
id integer Extension internal ID
number string Extension number
name string Extension display name
tech string Extension technology, for example SIP, PJSIP, VIRTUAL, or CUSTOM

Get Extension Information

This endpoint returns detailed information for one extension.

The extension can be selected by internal extension ID or by extension number.

When using the global full API key, the response also includes the extension password when a password exists for the extension technology.

Tenant API keys and read-only API keys do not return the extension password.

Endpoints

Get an extension by ID: 

GET openapi.php/extension?id=EXTENSION_ID

Alternative path format: 

GET openapi.php/extensions/EXTENSION_ID

Get an extension by number: 

GET openapi.php/extension?number=EXTENSION_NUMBER

Alternative path format: 

GET openapi.php/extensions/number/EXTENSION_NUMBER

Alternative compatibility format: 

openapi.php?object=extension&action=info&id=EXTENSION_ID
openapi.php?object=extension&action=info&number=EXTENSION_NUMBER

Parameters

Name Required Description
key Yes, unless using header authentication Full or read-only API key
tenant Required for tenant keys Tenant code or tenant name
id Required if number is not provided Extension internal ID
number Required if id is not provided Extension number

Use either id or number, not both.

When using a global API key without the tenant parameter, selecting by extension number can match more than one tenant. In that case the request returns an error and the request should be repeated using the tenant parameter or the extension ID.

Example Requests

Get by ID: 

curl "https://pbx.example.com/openapi.php/extension?id=101&tenant=TENANTCODE&key=APIKEY"

Get by number: 

curl "https://pbx.example.com/openapi.php/extension?number=100&tenant=TENANTCODE&key=APIKEY"

Using header authentication: 

curl \
  -H "X-API-Key: APIKEY" \
  "https://pbx.example.com/openapi.php/extension?number=100&tenant=TENANTCODE"

Example Response

The response includes all fields from the extension table, the normalized fields id, number, name, and tech, the current state when available, the technology username, technology-specific details, and related records.

Related records are returned in the related object. Depending on the extension configuration, this can include state information, registrations, PJSIP contacts, call groups, pickup groups, destinations, queue membership, allowed queue membership, user profile, routing profiles, client rate, caller ID regex, music on hold, parking lot, conditions, media files, and associated phones.

The me_data binary field from media files is not returned in this response. 

{
  "ex_id": "101",
  "ex_te_id": "1",
  "ex_name": "Reception",
  "ex_number": "100",
  "ex_tech": "PJSIP",
  "ex_tech_id": "55",
  "tenant_code": "TENANTCODE",
  "tenant_name": "Tenant Name",
  "id": 101,
  "number": "100",
  "name": "Reception",
  "tech": "PJSIP",
  "username": "100",
  "state": "NOT_INUSE",
  "st_state": "NOT_INUSE",
  "tech_details": {
    "endpoint": {
      "id": "100",
      "tech_id": "55",
      "te_id": "1"
    },
    "aor": {
      "id": "100",
      "max_contacts": "99"
    },
    "auth": {
      "id": "100",
      "username": "100"
    }
  },
  "related": {
    "state": {
      "st_extension": "100",
      "st_state": "NOT_INUSE"
    },
    "callgroups": [],
    "pickupgroups": [],
    "destinations": [],
    "referenced_by_destinations": [],
    "queue_members": [],
    "allowed_queue_members": [],
    "userprofile": {
      "up_id": "3",
      "up_name": "Basic user panel"
    },
    "routing_profile": {
      "rp_id": "1",
      "rp_name": "Default"
    },
    "sms_routing_profile": false,
    "client_rate": false,
    "callerid_regex": false,
    "callerid_regex_rules": [],
    "music_on_hold": false,
    "parkinglot": false,
    "conditions": [],
    "mediafiles": [],
    "phones": []
  }
}

When the global full API key is used, the response can also include: 

{
  "password": "extension_password"
}

Additional Error Responses

Missing Identifier

{
  "error": {
    "code": "missing_identifier",
    "message": "Provide an extension id or number."
  }
}

Invalid Identifier

{
  "error": {
    "code": "invalid_identifier",
    "message": "Use either id or number, not both."
  }
}

Extension Not Found

{
  "error": {
    "code": "extension_not_found",
    "message": "Extension not found."
  }
}

Multiple Extensions Found

{
  "error": {
    "code": "multiple_extensions_found",
    "message": "Multiple extensions match the requested number. Use the tenant parameter or the extension id."
  }
}

Error Responses

Errors are returned as JSON.

Missing API Key

{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key."
  }
}

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key."
  }
}

Tenant Not Found

{
  "error": {
    "code": "tenant_not_found",
    "message": "Tenant not found."
  }
}

Endpoint Not Found

{
  "error": {
    "code": "not_found",
    "message": "Endpoint not found."
  }
}

Method Not Allowed

Only GET is currently supported. 

{
  "error": {
    "code": "method_not_allowed",
    "message": "Only GET is supported by this endpoint."
  }
}

Notes

  • Read-only API keys are allowed for the extension list endpoint.
  • The endpoint does not create a web session.
  • Responses are always JSON.
  • CORS is enabled with Access-Control-Allow-Origin: *.
  • OPTIONS requests return HTTP 204 for browser preflight support.
Retrieved from "http://www.mirtapbx.com/manual/index.php?title=OpenAPI&oldid=2016"