TuCloudAPI

ℹ {{{1}}}

Overview

TuCloudAPI is the REST API to manage tucloud (the multi-tenant PBX, a.k.a. futurepbx). HTTPS, GET, JSON. Base URL:

https://tucloudapi.7kas.com:9087/tucloud?func=NAME&ukey=YOUR_KEY&pbx=PBX_NAME

Authentication & tenant

Every call needs an API key (ukey). The tasks functions also need pbx — the PBX name (e.g. tucall). The (ukey, pbx) pair is the tenant boundary: the server resolves the PBX name to its id and verifies the key owns it (SuperRoot any PBX; Operator its own root; Client its own account). It never trusts a numeric tenant from the caller.

Response format

Always HTTP 200. The tasks functions always return a JSON envelope: success {"ok":true, ...}, empty {"ok":true,"rows":[]}, error {"ok":false,"code":...,"message":...} (codes: missing_pbx, unknown_pbx, forbidden, invalid_param, not_found, db_error, server_busy). IDs are exposed as _id. Base/legacy functions return their data object directly, or {} on error/empty.

Functions

Extensions (Extensiones)

• TuCloudAPI getextensions — List the PBX extensions (safe display fields; NEVER the SIP password).
• TuCloudAPI getextension — Get one extension with all editable fields (NO password).
• TuCloudAPI getextlookups — Tenant-scoped option lists for the extension form selects: caller IDs (clis), music-on-hold (music), outgoing services (outs), and the extension list (exts, for Enviar a / backup monitor).
• TuCloudAPI addextension — Create an extension.
• TuCloudAPI updateextension — Edit an extension.
• TuCloudAPI deleteextension — Delete an extension after a tenant + dependency check.
• TuCloudAPI getextqr — SIP provisioning QR for one extension, rendered server-side to a PNG (base64).

CLIs / DIDs (Numeracion)

• TuCloudAPI getclis — List the PBX CLIs / DIDs (inbound numbers) with the grid fields.
• TuCloudAPI getcli — Get one CLI with all editable fields, including the full 192-key timer matrix under "timers".
• TuCloudAPI getclilookups — Tenant-scoped option lists for the CLI form: routes (all route selects), schedule profiles (template_h), and defined calendar templates (template_c helper).
• TuCloudAPI addcli — Create a CLI / DID.
• TuCloudAPI updatecli — Edit a CLI.
• TuCloudAPI deletecli — Delete a CLI after a tenant + dependency check.

Routes (Rutas)

• TuCloudAPI getroutes — List inbound routes for the PBX with step counts.
• TuCloudAPI getroute — Get one route header plus its ordered steps (destinations).
• TuCloudAPI getroutelookups — Tenant-scoped destination pickers for the step editor: the app enum plus extensions, groups, locutions, schedules, calendars and routes.
• TuCloudAPI addroute — Create an inbound route (header only; add steps with addroutestep).
• TuCloudAPI updateroute — Rename/annotate a route header.
• TuCloudAPI deleteroute — Delete a route.
• TuCloudAPI addroutestep — Append a step to a route (priority = max+1).
• TuCloudAPI updateroutestep — Change a step's app/appdata/timer (and optionally priority).
• TuCloudAPI deleteroutestep — Remove a step; the remaining steps' priorities are auto-compacted to 1..N by the DB trigger.

Blacklist (inbound intercept)

• TuCloudAPI getblacklist — List the inbound-intercept rules for the PBX.
• TuCloudAPI getblacklistlookups — Tenant-scoped pickers for the rule form: routes (the divert target) and CLIs/DIDs (cli_id; 0 = all DIDs / generic rule).
• TuCloudAPI addblacklist — Create an inbound-intercept rule.
• TuCloudAPI updateblacklist — Edit an inbound-intercept rule.
• TuCloudAPI deleteblacklist — Delete an inbound-intercept rule.

Contacts (Agenda)

• TuCloudAPI getcontacts — List the PBX contacts (address book).
• TuCloudAPI addcontact — Create a contact.
• TuCloudAPI updatecontact — Edit a contact.
• TuCloudAPI deletecontact — Delete a contact.

Calendar (date overrides)

• TuCloudAPI getcalendars — List the PBX calendar date-overrides (one row = one recurring month/day + time window that reroutes inbound to a route for CLIs on that template).
• TuCloudAPI getcalendar — Get one calendar row.
• TuCloudAPI getcalendarlookups — Tenant-scoped pickers: routes (the destination) and the set of template values already in use (suggestions for the template spinner).
• TuCloudAPI addcalendar — Create a calendar date-override.
• TuCloudAPI updatecalendar — Edit a calendar row (same fields as addcalendar).
• TuCloudAPI deletecalendar — Delete a calendar row.

Ring groups (Grupos)

• TuCloudAPI getgroups — List the PBX ring/hunt groups with a member count.
• TuCloudAPI getgroup — Get one group.
• TuCloudAPI getgrouplookups — Tenant-scoped pickers: extensions (members), music (MOH), and CLIs (for the admin forward caller-id).
• TuCloudAPI addgroup — Create a ring group.
• TuCloudAPI updategroup — Edit a ring group (same fields as addgroup; gr editable, conflict on collision).
• TuCloudAPI deletegroup — Delete a ring group.

Locutions / IVR (Locuciones)

• TuCloudAPI getlocutions — List the PBX locutions / IVR prompts.
• TuCloudAPI getlocution — Get one locution with its DTMF digit->route map (+ resolved route names), has_audio and audio_url.
• TuCloudAPI getlocutionlookups — Tenant-scoped route picker for the 11 DTMF digit destinations.
• TuCloudAPI addlocution — Create a locution / IVR.
• TuCloudAPI updatelocution — Edit a locution (name, waitext, digit routes).
• TuCloudAPI deletelocution — Delete a locution.

Music on hold (MOH)

• TuCloudAPI getmusics — List the PBX music-on-hold classes with has_audio (whether the track exists) and audio_url (the getaudio player URL).
• TuCloudAPI getmusic — Get one MOH class (+ has_audio, audio_url).
• TuCloudAPI addmusic — Create a MOH class.
• TuCloudAPI deletemusic — Delete a MOH class.

Schedules (Horarios)

• TuCloudAPI getschedules — List the PBX weekly schedules (the WHEN grid a CLI's schedule profile points at).
• TuCloudAPI getschedule — Get one schedule with the full 84-cell weekly grid under "slots".
• TuCloudAPI addschedule — Create a weekly schedule.
• TuCloudAPI updateschedule — Edit a schedule (template/name/grid).
• TuCloudAPI deleteschedule — Delete a schedule.

Outbound routing (Rutas de salida)

• TuCloudAPI getoutgoings — List the outbound-routing profiles (Servicios de salida) with rule counts.
• TuCloudAPI getoutgoing — Get one outbound profile plus its ordered allow/deny rules (longest-prefix first).
• TuCloudAPI getoutgoinglookups — Tenant-scoped route picker for a rule's divert destination (route_id; 0 = block).
• TuCloudAPI addoutgoing — Create an outbound-routing profile (header; add rules with addoutrule).
• TuCloudAPI updateoutgoing — Rename/annotate an outbound profile.
• TuCloudAPI deleteoutgoing — Delete an outbound profile.
• TuCloudAPI addoutrule — Append an allow/deny rule to a profile.
• TuCloudAPI updateoutrule — Edit an outbound rule (dst/denyallow/route_id/nota).
• TuCloudAPI deleteoutrule — Remove an outbound rule.

Phonebooks (Agendas)

• TuCloudAPI getphonebooks — List the PBX phonebooks (address books) with contact counts.
• TuCloudAPI getphonebook — Get one phonebook plus its contacts.
• TuCloudAPI addphonebook — Create a phonebook.
• TuCloudAPI updatephonebook — Edit a phonebook.
• TuCloudAPI deletephonebook — Delete a phonebook and all its contacts (DB cascade).
• TuCloudAPI addphonebookcontact — Add a contact to a phonebook.
• TuCloudAPI updatephonebookcontact — Edit a phonebook contact (tenant-checked via the row).
• TuCloudAPI deletephonebookcontact — Remove a phonebook contact (tenant-checked).

Call queues / ACD (Colas)

• TuCloudAPI getqueues — List the PBX call queues (ACD) with member counts.
• TuCloudAPI getqueue — Get one queue's config.
• TuCloudAPI getqueuelookups — Tenant-scoped pickers for the queue form: music (MOH classes) and the strategy enum.
• TuCloudAPI addqueue — Create a call queue.
• TuCloudAPI updatequeue — Edit a queue's config.
• TuCloudAPI deletequeue — Delete a queue.

Portal admin users (Usuarios)

• TuCloudAPI getadminusers — List portal admin users (tucloud_sec_users) in the caller's scope.
• TuCloudAPI getadminuser — Get one portal admin user by login (_id).
• TuCloudAPI getadminuserlookups — Pickers for the admin-user form: distinct existing roles + the tucloud_pbx list in scope (the tucloudpbx_id picker).
• TuCloudAPI addadminuser — Create a portal admin user.
• TuCloudAPI updateadminuser — Edit a portal admin user.
• TuCloudAPI deleteadminuser — Delete a portal admin user by login.

PBX settings (Configuracion)

• TuCloudAPI getpbxconfig — Get this PBX's settings (single record ? no id needed, tenant from the binding).
• TuCloudAPI getpbxconfiglookups — Picker for the admin_ext_id field: this PBX's extensions.
• TuCloudAPI updatepbxconfig — Update this PBX's settings (strict set).

Scheduled tasks (Tareas programadas)

• TuCloudAPI gettasks — List scheduled tasks (tareas programadas) for the PBX, with schedule + status labels and step counts.
• TuCloudAPI gettask — Get one scheduled task and its ordered steps.
• TuCloudAPI gettasksteps — Get the ordered steps of a task (tenant-checked).
• TuCloudAPI gettasklog — Get the last 100 execution-log rows for a task (read-only history), newest first.
• TuCloudAPI getapps — List the 8 target entity types ("apps") a task step can act on.
• TuCloudAPI getappactions — List the configurable fields ("actions") for an app — the dynamic-form catalog (field, type 0-5, data, metadata).
• TuCloudAPI getappsrecords — List this PBX's selectable records for an app (the record picker), via the tenant-scoped lookup function.
• TuCloudAPI getactiondata — List the selectable value options for an action (the value picker), for select/checkbox action types, via the tenant-scoped lookup function.
• TuCloudAPI getpbxs — List the PBXs assigned to the calling ukey's account (post-login selector; show only if >1).
• TuCloudAPI addtask — Create a scheduled task (status forced 0).
• TuCloudAPI updatetask — Edit a task (does not change status).
• TuCloudAPI deletetask — Delete a task (DB cascade of steps/log + crontab removal via the operator trigger).
• TuCloudAPI addtaskstep — Append a step to a task.
• TuCloudAPI updatetaskstep — Change a step's value (blank -> NULL).
• TuCloudAPI deletetaskstep — Remove a step.

Call simulator

• TuCloudAPI simulatecall — Simulate how a call routes (inbound DID / outbound / internal) WITHOUT placing a real call, returning the ordered decision trace (flujo).

Audio files

• TuCloudAPI getaudio — General-purpose audio file server (not only for the simulator): serve a locution or music-on-hold audio file base64-encoded (audio/wav) — for hover-preview, players, downloads, etc.

Tucloud PBX

• TuCloudAPI getpbxloclog — Tucloud PBX IVR/locution DTMF key-press log for a period.

Meta / discovery

• TuCloudAPI help — Lists the API functions available to the role of the calling ukey, with each function's description, parameters (meaning, optional/default), an example call and the response format.

Diagnostics

• TuCloudAPI helloworld — Health check / connectivity test.

Administration

• TuCloudAPI SetDebugLevel — Sets the runtime debug/log verbosity level.
• TuCloudAPI ReloadUsersKeys — Hot-reloads the API keys from the database without restarting the service.
• TuCloudAPI resetinternalkey — Regenerates the non-showable internal API key for an account.

Account management (inherited)

• TuCloudAPI getaccountcodeid — Lists (id, accountcode) pairs of the accounts under the caller.
• TuCloudAPI getaccountcodedata — Returns full account profile rows (view_voip_users_api) for the caller's accounts.
• TuCloudAPI lockaccountcode — Blocks (locks) an account (blocked=SI).
• TuCloudAPI unlockaccountcode — Unblocks (unlocks) an account (blocked=NO).
• TuCloudAPI addaccountcode — Creates a new account (client) under the caller.
• TuCloudAPI getcredit — Returns credit and status (credit, credit_limit, creditalarm, email, blocked).

Related

Full technical reference (architecture, auth model, side effects): see the project repo doc/TUCLOUDAPI_REFERENCE.md. Scheduled-tasks engine: the 6 tucloud_pbx_tasks* tables + the .231 crontab trigger.