TuCloudAPI

ℹ New here? Start with the self-discovery endpoint. This reference is generated from func=help, so it never drifts.

Overview

TuCloudAPI is the REST API to manage FuturePBX (the multi-tenant cloud PBX). HTTPS + JSON, GET or POST (parameters form-urlencoded; audio uploads POST the file as the body). 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). Every PBX-scoped function also needs 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 that the key's OWN account owns it — for every role, SuperRoot included. A PBX that does not exist and one the key does not own both answer forbidden. It never trusts a numeric tenant from the caller.

Response format

Always HTTP 200. Every PBX-scoped function always returns a JSON envelope: success {"ok":true, ...}, empty {"ok":true,"rows":[]}, error {"ok":false,"code":...,"message":...} (common codes: missing_pbx, forbidden, invalid_param, not_found, conflict, in_use, db_error, server_busy). IDs are exposed as _id. A missing or invalid ukey answers a bare {} and nothing else. The legacy account functions return their data object directly, {} when there is nothing.

Functions

Dashboard (landing counts)

TuCloudAPI getdashboard — Landing-page dashboard: per-tenant object counts + a cheap health metric, in one call.

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), the extension list (exts, for Enviar a / backup monitor), registration servers (servers) and next_free: the create-form number prefill for a REGISTERED extension (3-4 digits, the same check as checkextnum), a string, or null when no number is free.
TuCloudAPI checkextnum — Is this number free for a NEW extension of this PBX? The same check addextension runs under its lock, so the two never disagree.
TuCloudAPI addextension — Create an extension.
TuCloudAPI updateextension — Edit an extension.
TuCloudAPI deleteextension — Delete an extension after a tenant + dependency check.
TuCloudAPI setextpassword — Rotate ONE extension's SIP password.
TuCloudAPI getextpassword — Plaintext SIP password for ONE extension (the portal's «Clave SIP» eye toggle).
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, routes and queues (app=10 "Cola": _id = the stable voip_queue.id stored in the step appdata, label = the queue title).
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 and period rule 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.
TuCloudAPI getlocutionvoices — Catalogo para el selector de texto a voz: voces disponibles e idiomas admitidos.
TuCloudAPI synthlocution — Genera el audio de una locucion a partir de un texto y lo deja PENDIENTE DE ACEPTAR: NO sustituye la locucion.
TuCloudAPI uploadlocution — Sube un fichero de audio y lo deja COMO el audio de una locucion.
TuCloudAPI commitlocution — Acepta el audio pendiente (el generado por synthlocution o subido por uploadlocution) y lo convierte en la locucion.
TuCloudAPI discardlocution — Tira el audio pendiente sin tocar la locucion.

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 uploadmusic — Sube un fichero de audio para una clase de musica y lo deja PENDIENTE DE ACEPTAR: NO sustituye la que suena.
TuCloudAPI commitmusic — Acepta el audio pendiente y lo convierte en la musica que suena.
TuCloudAPI discardmusic — Tira el audio pendiente sin tocar la musica.
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), the strategy enum, and next_free (the create-form exten prefill = first free 3-digit queue number, null if 900-999 full).
TuCloudAPI addqueue — Create a call queue.
TuCloudAPI updatequeue — Edit a queue's config.
TuCloudAPI deletequeue — Delete a queue.

Agents / queue members (Agentes)

TuCloudAPI getagents — List the PBX agents (queue members) with the queue title and the agent's extension name resolved.
TuCloudAPI getagentlookups — Dropdown data for the agent screens: this PBX's queues (assign an agent to a queue) and its extensions {_id,num,name}.
TuCloudAPI addagent — Add an extension to a queue as a static member.
TuCloudAPI updateagent — Update a queue member's penalty / paused / reason_paused (partial — only the fields sent are changed).
TuCloudAPI deleteagent — Remove a queue member (agent) by _id.

Portal admin users (Usuarios)

TuCloudAPI getadminusers — List this PBX's portal users (tucloud_sec_users).
TuCloudAPI getadminuser — Get one portal user by login (_id) within this PBX.
TuCloudAPI getadminuserlookups — Picker for the user form: the distinct roles used in this PBX (free-text datalist suggestions), and invite:true: users are created by email invitation, with no username and no password (always true on this build).
TuCloudAPI addadminuser — Invite a new portal user to THIS PBX.
TuCloudAPI updateadminuser — Edit a portal user in THIS PBX: name, active, priv_admin, role and phone are replaced as sent; disable_2fa=1 turns 2FA off and clears the secret (never enables).
TuCloudAPI requestadminuseremail — Ask to change a portal user's EMAIL (their magic-link login), the twin of requestpbxemail.
TuCloudAPI resendadminuseremail — Mail again the link of the user's open email change (the invitation of an invited user, or a change), pending or expired, with a fresh 24 hours; the previous link is then ignored.
TuCloudAPI canceladminuseremail — Drop the user's open email change (pending, or expired): its link is then ignored.
TuCloudAPI getadminuseremailchange — Status of the user's latest email change, from tucloudapi's own state (never magiclogin): none | pending (email, expires_in) | expired (until resent or cancelled) | done (notice: sent|failed|skipped, the informational mail to the old address) | failed (reason taken|error) | cancelled, with invite (true when it is the invitation) and its Spanish message.
TuCloudAPI deleteadminuser — Delete a portal user by login within this PBX; their open email change is cancelled with them.

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).
TuCloudAPI requestpbxemail — Ask to change this PBX's MASTER EMAIL (tucloud_pbx.email: the administrator's magic-link and password login).
TuCloudAPI getpbxemailchange — Status of this PBX's latest master-email change, from tucloudapi's own state (never magiclogin): none | pending (email, expires_in) | done (email, notice: sent|failed|skipped, the informational mail to the old address) | expired | failed (reason taken|error) | cancelled, each with its Spanish message.
TuCloudAPI cancelpbxemail — Cancel this PBX's pending master-email change (its link is then ignored).

Security profiles / ACL (Perfiles)

TuCloudAPI getprofiles — List this PBX's security profiles (Perfiles) with member counts.
TuCloudAPI getprofile — Get one profile + its full app-permission matrix (all catalog apps, with app_type).
TuCloudAPI getprofileapps — Get a profile's app-permission matrix only (the Aplicaciones/Perfiles editor).
TuCloudAPI getseclookups — Pickers for the security section: the global app catalog (matrix columns) + this PBX's profiles (membership picker).
TuCloudAPI getprofileusers — List the admin users assigned to a profile (read-only "Miembros" list; edits stay per-user via setuserprofiles).
TuCloudAPI getuserprofiles — Get an admin user's profile membership + the profile picker (this PBX only).
TuCloudAPI addprofile — Create a security profile in this PBX.
TuCloudAPI updateprofile — Rename a profile (description).
TuCloudAPI deleteprofile — Delete a profile.
TuCloudAPI getsections — The catalog of portal sections (login v2, 2026-10-31): one row per section of the new web, in sidebar order, from the NEW table tucloud_sec_sections (24 rows; pbx_config is the PBX administrator's and has no row).
TuCloudAPI getprofilesections — One profile's section access (login v2): every catalog section with access Y/N, from the NEW table tucloud_sec_groups_sections; a section without a row answers N.
TuCloudAPI setprofilesections — FULL replace of one profile's section access (login v2; the «mantenimiento de accesos de los grupos» the operator asked for on 2026-10-31).
TuCloudAPI setprofileapps — RETIRED 2026-10-31 (operator: the legacy matrix is never altered again).
TuCloudAPI setprofileapp — RETIRED 2026-10-31 (operator: the legacy matrix is never altered again).
TuCloudAPI setuserprofiles — Full-replace an admin user's profile membership (this PBX only).

Call detail records (CDR)

TuCloudAPI getcdr — List a period of this PBX's call detail records (Registro de llamadas), newest first.
TuCloudAPI getcdrlookups — CDR form pickers: the selectable years + the result (disposition) label set.

Reports / statistics (Informes)

TuCloudAPI getreports — Call-volume statistics (Informes / Estadisticas de Llamadas) for a month — VOLUME ONLY, no prices.

AI assistant (Asistente IA)

TuCloudAPI aichat — AI assistant for this PBX (Spanish).

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.

FuturePBX

TuCloudAPI getpbxloclog — FuturePBX 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).

auth

TuCloudAPI authrequest — Ask for a magic-link e-mail.
TuCloudAPI authpoll — Has the user authorized the magic link? PUBLIC, like authrequest.
TuCloudAPI authchallenge — A proof-of-work captcha challenge (ALTCHA protocol, SHA-256).
TuCloudAPI authlogin — The password door.
TuCloudAPI authwhoami — The current session context, and it refreshes the idle timer.
TuCloudAPI authlogout — Destroy the session and clear the cookie.

queue_live

TuCloudAPI getqueueevents — Today's events of ONE queue (local day), newest first, at most 200, with the same deduplication as getqueuestats (core events; module EXITQUEUE FULL/JOINEMPTY kept as refused).
TuCloudAPI getlivestatus — LIVE state of the PBX as ONE snapshot of the presence feed: each extension's state (unregistered/idle/ringing/busy, "unknown" when it is not published) and its calls in progress (ringing/talking/hold/dialing, the other party, seconds since start and since answer), and each queue's live picture (agents logged in / available / paused, the waiting calls in queue order with their wait, every member with its status).

queue_stats

TuCloudAPI getqueuestats — Call-center history from voip_queue_log (gabpbx contract v1, 2026-10-31): totals, per interval, per queue and per agent between two local days (Europe/Madrid, inclusive).