Maintenance script: Operator API reference (generated from func=help)

2026-08-19T08:16:07Z

Operator API reference (generated from func=help)

New page

{{Note|1=New here? Start with '''[[OperatorAPI help|the self-discovery endpoint]]'''. This whole reference is generated from the service's own <code>func=help</code>, so it never drifts from the code.}}

== Overview ==
'''Operator API''' (newadmapi / Helm) is the REST API a brand operator uses to manage its services. '''HTTPS, GET or POST, JSON.''' One route, one dispatch parameter:
https://YOUR_HOST:9089/newadm?func=NAME&...

== Authentication ==
Every request carries your '''API key''' - as <code>X-API-Key: YOUR_KEY</code>, <code>Authorization: Bearer YOUR_KEY</code>, or the <code>ukey</code> query parameter. The key identifies the operator and its tenant (root); the service NEVER trusts a tenant supplied in the request body. Write paths always stamp the caller's own root.

== Response envelope ==
Every answer is a JSON envelope. Success: <code>{"ok":true,"data":{...}}</code> (an empty result set is still <code>ok:true</code>). Refusal: <code>{"ok":false,"code":"...","message":"..."}</code>. '''Branch on <code>code</code>, never on the message text''' - the message is human-facing and may change; the code is the contract.

== Error codes ==
{| class="wikitable"
! Code !! Meaning
|-
| <code>auth_missing</code> || no API key was sent
|-
| <code>auth_invalid</code> || the key is not valid
|-
| <code>auth_busy</code> || the key's concurrency limit is reached - retry later
|-
| <code>forbidden</code> || the key's role may not do this
|-
| <code>readonly</code> || this key may only read
|-
| <code>unknown_func</code> || no such function
|-
| <code>invalid_param</code> || a value is out of range or the wrong type (named)
|-
| <code>unknown_param</code> || a field that is not part of this section/function
|-
| <code>count_mismatch</code> || a bulk delete's stated count did not match the set
|-
| <code>server_busy</code> || the pool is momentarily exhausted - retry later
|-
| <code>server_error</code> || a server-side fault; retrying the same request will not help
|}

== How the sections work ==
Most data lives in '''sections''' (bonos, cli, tucloudpbx, didstock, ...). Two discovery calls, then the generic verbs:
* [[OperatorAPI sections]] - which sections you can see, and what you may do in each.
* [[OperatorAPI options]] - one section's published fields, pickers, search, export and what a delete would cascade to.
* then [[OperatorAPI list]] / [[OperatorAPI get]] / [[OperatorAPI insert]] / [[OperatorAPI update]] / [[OperatorAPI delete]] / [[OperatorAPI export]] / [[OperatorAPI lookup]] operate over any section via <code>section=</code>.

== Functions ==
=== Discovery & meta ===
* [[OperatorAPI help]] — Lists the API functions this key's role may call, with parameters, an example and the response shape.
=== Generic verbs (over any section) ===
* [[OperatorAPI delete]] — Removes one row, addressed by id, within your tenant.
* [[OperatorAPI export]] — The SAME query as list, rendered as a delimited file.
* [[OperatorAPI get]] — One row of a section, by id, tenant-scoped and projected through the SAME declared field list as list - so an edit form can never receive a column the grid would not show.
* [[OperatorAPI insert]] — Creates a row in a section.
* [[OperatorAPI list]] — Lists any served section.
* [[OperatorAPI lookup]] — One writable field's picker, served for a GIVEN root instead of baked into the func=options contract for your own.
* [[OperatorAPI options]] — What a SECTION offers, and what THIS caller may do with it: the readable fields with their types and whether each is sortable or searchable, the writable fields with required/immutable, the group writes demand, the export choices, and what a delete would cascade to.
* [[OperatorAPI sections]] — Every section this service serves, with what each offers and what THIS caller may do with it.
* [[OperatorAPI update]] — Changes declared fields of one row, addressed by id.
=== Login & session ===
* [[OperatorAPI login]] — Exchanges an operator ukey for a short, revocable session.
* [[OperatorAPI poll]] — Polls a login started with func=request.
* [[OperatorAPI request]] — Starts an operator login.
* [[OperatorAPI session:menu]] — The menu this operator may see, NESTED as the legacy renders it: the rows of web_menus for their root, filtered by their groups, built into containers and leaves.
=== PBX / TuCloud ===
* [[OperatorAPI aindirecto:list]] — Lists indirect-access / preassignment records.
* [[OperatorAPI cli:list]] — Lists the inbound numbers of the caller's tenant.
* [[OperatorAPI click2call:list]] — Lists the click-to-call entries of the caller's tenant.
* [[OperatorAPI click2callinmovilla:list]] — Lists the Inmovilla click-to-call agency links.
* [[OperatorAPI didhist:list]] — Numbering history - when each DID was opened and closed.
* [[OperatorAPI didstock:list]] — Lists the numbering STOCK.
* [[OperatorAPI end:list]] — Lists customer endpoints.
* [[OperatorAPI extensions:list]] — Lists the DIALPLAN - voip_extensions_conf, the rows that make a number ring.
* [[OperatorAPI incomingcalls:list]] — Lists inbound call history.
* [[OperatorAPI llamadasac:list]] — Lists ALL calls in progress, from view_voip_calls_active - a DIFFERENT view and a DIFFERENT TENANT COLUMN (r_root, not root), both verified against information_schema.
* [[OperatorAPI llamadasacentrantes:list]] — Lists inbound calls IN PROGRESS - the same view as incomingcalls with the same flags bit SET rather than clear ("flags & 8 = 8").
* [[OperatorAPI pas:list]] — Lists the bridge/callback gateway entries of the caller's tenant.
* [[OperatorAPI pbx:list]] — Lists virtual PBXs (centralitas).
* [[OperatorAPI pbxext:list]] — Lists REAL PBX extensions - wcl_clientes_ext narrowed by the legacy's own two unconditional restrictions: virt = 0, and context <> the CALLER'S OWN dialplan context.
* [[OperatorAPI pbxfax:list]] — Lists the fax-to-email extensions of the caller's tenant.
* [[OperatorAPI pbxsal:list]] — Conference rooms.
* [[OperatorAPI pbxvirext:list]] — Lists VIRTUAL extensions - wcl_clientes_ext narrowed by the legacy's own unconditional restriction virt = 1, carried in Extra.
* [[OperatorAPI porta:list]] — Number portability requests.
* [[OperatorAPI tucdevices:list]] — Lists the TuCloud devices of the caller's tenant.
* [[OperatorAPI tucfiles:list]] — Lists device configuration files.
* [[OperatorAPI tucloudpbx:list]] — Lists the TuCloud cloud PBXs.
* [[OperatorAPI tucloudpbxcli:list]] — Lists the numbers attached to each cloud PBX.
* [[OperatorAPI tucloudpbxen:list]] — Lists the cloud PBXs.
* [[OperatorAPI voicemail:list]] — Customer voicemail boxes.
* [[OperatorAPI vtun:list]] — Lists customer VPN tunnels.
=== Platform ===
* [[OperatorAPI opap:list]] — Which groups reach each application - the access-control data itself.
* [[OperatorAPI opme:list]] — Which groups reach each menu option.
* [[OperatorAPI opus:list]] — Lists the ADMIN ACCOUNTS of the adm application - wad_admins, the table every caller authenticates against.
* [[OperatorAPI ssipdevices:list]] — Lists the SecureSIP devices.
=== Rates ===
* [[OperatorAPI destinos:list]] — Lists the shared dialling-plan destinations.
* [[OperatorAPI pro:list]] — Lists the upstream carriers.
* [[OperatorAPI protar:list]] — Lists the DRAFT provider rates - the staging copy edited before promotion.
* [[OperatorAPI protarde:list]] — Lists the LIVE provider rates - the promoted copy the platform buys at.
* [[OperatorAPI usertardraft:list]] — Lists STAGED customer sale rates - the drafts sys_update_all_rates makes live once entrance <= now.
* [[OperatorAPI usertaresp:list]] — Lists the special-price IMPORT STAGING rows.
=== Tariffs ===
* [[OperatorAPI usertar:list]] — Lists the customer tariffs of the caller's tenant.
* [[OperatorAPI usertarde:list]] — Lists LIVE customer sale rates (the draft's twin, over view_voip_rates).
=== Billing ===
* [[OperatorAPI bbonos:list]] — Call consumption for customers holding bundles.
* [[OperatorAPI billing:list]] — Lists BILLED CALL HISTORY.
* [[OperatorAPI billingbyday:list]] — Daily consumption per customer, for the OPERATOR audience: the _r view, scoped by r_root.
* [[OperatorAPI billingbymonth:list]] — Monthly consumption per customer, operator audience.
* [[OperatorAPI billingday:list]] — The same grid and the same decoded mask as billing, over view_voip_calls instead of view_voip_calls_hist - today's calls rather than the archive.
* [[OperatorAPI recman:list]] — Lists manual credit entries (prepaid top-ups).
=== Bundles (bonos) ===
* [[OperatorAPI bonos:list]] — Lists the VoIP minute bundles of the caller's tenant.
* [[OperatorAPI bonoscounter:list]] — Lists per-period bundle consumption counters.
* [[OperatorAPI bonosdst:list]] — Lists the destination prefixes belonging to a VoIP bundle, for the caller's tenant.
* [[OperatorAPI bonosusers:list]] — Lists which customer extensions hold which bundle.
=== SIP ===
* [[OperatorAPI sip:list]] — Lists the SIP configurations of the caller's tenant.
=== Payments ===
* [[OperatorAPI recargas:list]] — Lists TPV recharges - every payment of the tenant, unfiltered, which is the legacy's own lock.
=== Customers ===
* [[OperatorAPI user:list]] — Lists the customers of the caller's tenant.

''Generated from <code>func=help</code> as the operator role. Regenerate after any change to the service's registered functions.''
[[Category:OperatorAPI]]

OperatorAPI - Revision history

Maintenance script: Operator API reference (generated from func=help)