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).

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.