Numbers

A protected number is one of yours that we score calls on. It is created the first time a call arrives on it, or here, on purpose, with its settings.

List numbers

GET/v1/numbersany key

Every protected number, oldest first, with the last hour on each and where it stands against its own usual volume.

Response

e164 / labelstring / string | null
settingsobject: ceiling_min, protection, scope, spend_ceiling_usd, whichever have been set.
gate_tokenstring: The credential in the gate URLs for this number.
gate_mode / gate_provider / gate_destinationstring: See the gate. gate_engaged_until is set while an adaptive gate is challenging everyone.
watch_outboundboolean: Whether calls placed from this number are scored too.
connection_id / source_provider / source_labelstring | null: The platform connection it was imported from, if any.
client_id / client_namestring | null: Who the number is protected on behalf of, when you have clients.
calls_last_hour / outbound_last_hour / open_callsinteger
spend_7dnumber: USD, on calls that carried a cost.
volumeobject: status (learning, normal, above, below or spike) with calls in the window, the expected count, and how many history_days the baseline has.

RequestShell

BASE=https://api.murusai.com

curl "$BASE/v1/numbers" \
  -H "Authorization: Bearer $MURUSAI_KEY"

RequestNode

const BASE = "https://api.murusai.com";
const KEY = process.env.MURUSAI_KEY;

const url = new URL("/v1/numbers", BASE);
const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${KEY}`,
  },
});
const data = await res.json();

RequestPython

import os, requests

BASE = "https://api.murusai.com"
KEY = os.environ["MURUSAI_KEY"]

r = requests.get(
    f"{BASE}/v1/numbers",
    headers={"Authorization": f"Bearer {KEY}"},
)
data = r.json()

200OKResponseJSON

{
  "numbers": [
    {
      "e164": "+14155550100",
      "label": "Main line",
      "settings": { "ceiling_min": 20 },
      "created_at": "2026-08-02T18:20:11.000Z",
      "gate_token": "gt_7mKp…",
      "gate_mode": "adaptive",
      "gate_provider": "twilio",
      "gate_destination": "https://agent.example.com/voice",
      "gate_engaged_until": null,
      "watch_outbound": false,
      "connection_id": null,
      "source_provider": null,
      "source_label": null,
      "client_id": null,
      "client_name": null,
      "calls_last_hour": 31,
      "outbound_last_hour": 0,
      "open_calls": 1,
      "spend_7d": 251.2,
      "volume": {
        "status": "spike",
        "calls": 31,
        "expected": 9.5,
        "history_days": 41
      }
    }
  ]
}

Protects a number, or changes the settings on one already protected; the same call does both, and only the fields you send change. A new number pulls its last thirty days from every platform connection in the background, so it starts with a memory.

Request body

numberstringrequired: E.164.
labelstring: For your own eyes.
protection"relaxed" | "standard" | "strict" | null: A level for this number alone; null puts it back on the account's. See protection.
ceiling_mininteger, 1–600: How long a call on this number may run before a call.long_running alert.
spend_ceiling_usdnumber, 1–100000 | null: Spend in one hour on this number past which a number.spend_exceeded alert fires. null clears it; the alert then waits for a week of cost history and derives its own.
watch_outboundbooleandefault false: Score calls placed from this number as well as calls to it.
gate_mode"off" | "adaptive" | "always"default "off": Anything but off needs Guard.
gate_provider"twilio" | "telnyx" | "signalwire" | "vonage"default "twilio": Which carrier's dialect the gate speaks. Set for you when the number came from a carrier connection.
gate_destinationstring: Where the call goes after the gate: a URL, a phone number, or a sip: address. Vonage cannot take a URL.
connectionstring: The id of the platform connection the number belongs to.
clientstring | null: The id of the client this number is protected for; null to clear.
scopestring: A note on what the number is for, up to 120 characters.

Response

…object: The number, as in the list, without the counts.
backfillingboolean: true when the number is new and its history is being pulled.

Errors

invalid_number400: Not E.164.
number_limit402: Your plan's cap, with the limit in the body.
number_taken409: Another account already protects it.
plan_required402: A gate mode other than off on Watch.
invalid_gate_destination400: Not a URL, a phone number, or a sip: address.
vonage_needs_phone_or_sip400: A URL destination with the Vonage gate.
invalid_ceiling / invalid_spend_ceiling / invalid_protection / invalid_gate_mode / invalid_gate_provider400: A value outside its set.
unknown_connection / unknown_client400: An id that is not yours.

RequestShell

BASE=https://api.murusai.com

curl -X POST "$BASE/v1/numbers" \
  -H "Authorization: Bearer $MURUSAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+14155550100",
    "label": "Main line",
    "protection": "strict",
    "ceiling_min": 15
  }'

RequestNode

const BASE = "https://api.murusai.com";
const KEY = process.env.MURUSAI_KEY;

const url = new URL("/v1/numbers", BASE);
const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "number": "+14155550100",
    "label": "Main line",
    "protection": "strict",
    "ceiling_min": 15
  }),
});
const data = await res.json();

RequestPython

import os, requests

BASE = "https://api.murusai.com"
KEY = os.environ["MURUSAI_KEY"]

r = requests.post(
    f"{BASE}/v1/numbers",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "number": "+14155550100",
        "label": "Main line",
        "protection": "strict",
        "ceiling_min": 15,
    },
)
data = r.json()

201CreatedResponseJSON

{
  "e164": "+14155550100",
  "label": "Main line",
  "settings": { "protection": "strict", "ceiling_min": 15 },
  "created_at": "2026-09-21T02:20:00.000Z",
  "gate_token": "gt_7mKp…",
  "gate_mode": "off",
  "gate_provider": "twilio",
  "gate_destination": null,
  "gate_engaged_until": null,
  "connection_id": null,
  "client_id": null,
  "watch_outbound": false,
  "backfilling": true
}

402Payment RequiredResponseJSON

{ "error": "number_limit", "limit": 3 }

Remove a number

DELETE/v1/numbers/{number}full key

Stops protecting it. The calls already recorded on it stay in your log; a new call on it would add it back, unless you send register: false.

Path parameters

numberstringrequired: E.164, plus encoded: %2B14155550100.

Response

removedboolean

RequestShell

BASE=https://api.murusai.com

curl -X DELETE "$BASE/v1/numbers/%2B14155550100" \
  -H "Authorization: Bearer $MURUSAI_KEY"

RequestNode

const BASE = "https://api.murusai.com";
const KEY = process.env.MURUSAI_KEY;

const url = new URL("/v1/numbers/%2B14155550100", BASE);
const res = await fetch(url, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${KEY}`,
  },
});
const data = await res.json();

RequestPython

import os, requests

BASE = "https://api.murusai.com"
KEY = os.environ["MURUSAI_KEY"]

r = requests.delete(
    f"{BASE}/v1/numbers/%2B14155550100",
    headers={"Authorization": f"Bearer {KEY}"},
)
data = r.json()

200OKResponseJSON

{ "removed": true }

Volume on a number

GET/v1/numbers/{number}/volumeany key

Where one number stands against its own history: this hour against what this hour usually brings, this week against last, who is calling, when it is usually busy, the spikes it has had, and what it is costing. The number's page in the dashboard is drawn from this.

Path parameters

numberstringrequired: E.164, plus encoded.

Response

ready / history_days / min_history_daysboolean / integer / integer: Whether the baseline has enough history to mean anything: fourteen days of the number's own calls.
nowobject: calls and distinct callers in the last window_min minutes, and the expected count for this hour of this kind of day.
spikeobject | null: An open spike: since, peak, callers, expected.
weekobject: calls and minutes this week and _prev for last; flagged; distinct callers and how many were new_callers; the busiest hour.
heatmapobject[]: Mean calls per hour by day of week: dow, hour, mean.
spikesobject[]: Past spikes, each with since, until, peak, expected, callers.
seriesobject[]: Hourly points for the last seven days, each with the calls in that hour and the baseline expected for it.
momentumobject: How fast volume is moving right now, against the expected rate, with a short series behind it.
spendobject: hour in USD and hour_calls; the usual for this hour once there is history; the ceiling in force and whether you ceiling_set it; week and week_prev; the costliest call.

Errors

invalid_number400: Not E.164.

RequestShell

BASE=https://api.murusai.com

curl "$BASE/v1/numbers/%2B14155550100/volume" \
  -H "Authorization: Bearer $MURUSAI_KEY"

RequestNode

const BASE = "https://api.murusai.com";
const KEY = process.env.MURUSAI_KEY;

const url = new URL("/v1/numbers/%2B14155550100/volume", BASE);
const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${KEY}`,
  },
});
const data = await res.json();

RequestPython

import os, requests

BASE = "https://api.murusai.com"
KEY = os.environ["MURUSAI_KEY"]

r = requests.get(
    f"{BASE}/v1/numbers/%2B14155550100/volume",
    headers={"Authorization": f"Bearer {KEY}"},
)
data = r.json()

200OKResponseJSON

{
  "number": "+14155550100",
  "ready": true,
  "history_days": 41,
  "min_history_days": 14,
  "now": {
    "calls": 31,
    "callers": 22,
    "expected": 9.5,
    "window_min": 60
  },
  "spike": {
    "since": "2026-09-21T01:40:00.000Z",
    "peak": 31,
    "callers": 22,
    "expected": 9.5
  },
  "week": {
    "calls": 612, "calls_prev": 540,
    "minutes": 1830, "minutes_prev": 1650,
    "flagged": 19,
    "callers": 401, "new_callers": 88,
    "busiest": { "at": "2026-09-21T02:00:00.000Z", "calls": 31 }
  },
  "heatmap": [ { "dow": 1, "hour": 14, "mean": 8.2 }, { … } ],
  "spikes": [ { … } ],
  "series": [ { … } ],
  "momentum": { … },
  "spend": {
    "hour": 12.4, "hour_calls": 31,
    "usual": 3.9, "history_days": 41,
    "ceiling": 10, "ceiling_set": true,
    "week": 251.2, "week_prev": 220.9, "week_calls": 612,
    "costliest": {
      "call_id": "CA7f3e2a91c04b",
      "cost": 2.15,
      "caller": "+15125550142",
      "started_at": "2026-09-21T02:14:07.000Z"
    }
  }
}

A number can belong to one account. If another account protects it, adding it answers 409 number_taken. Write to support with proof it is yours and we move it.

Numbers

List numbers

Response

Add or update a number

Request body

Response

Errors

Remove a number

Path parameters

Response

Volume on a number

Path parameters

Response

Errors