Blocks

A block is a number, or a run of numbers, that scores as bad as it gets until a time. Most are placed by us; you can place and lift your own.

A block

patternstring: The number, or the run it belongs to: a stem like +151255501 covers every number that starts that way.
type"manual" | "exact" | "stem" | "volume": manual is yours. exact and stem are ours, placed after a number or a run misbehaved. volume is on your own protected number, when it takes far more calls than it should in an hour.
untilstring: When it lifts, ISO 8601.
remaining_sinteger: Seconds until then.
violationsinteger: How many times the pattern has earned a block. Each one lasts longer than the last, up to a day.

A block does not refuse a call by itself: it makes the next call from the pattern score as a reject, and it is Guard, the gate, or your own code acting on that score that refuses it. On Watch a block is a fact you are told, not an action we take.

List blocks

GET/v1/blocksany key

Every block in force, the one lifting last first. With all=1, every block the account has ever had, newest first, up to a hundred, each marked active or not.

Query parameters

all1: History instead of the current state.

Response

blocksobject[]: Blocks, as above. In history rows, created_at and updated_at replace remaining_s.

RequestShell

BASE=https://api.murusai.com

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

RequestNode

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

const url = new URL("/v1/blocks", 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/blocks",
    headers={"Authorization": f"Bearer {KEY}"},
)
data = r.json()

200OKResponseJSON

{
  "blocks": [
    {
      "pattern": "+151255501",
      "type": "stem",
      "until": "2026-09-21T02:44:07.000Z",
      "remaining_s": 1622,
      "violations": 1
    },
    {
      "pattern": "+12125550143",
      "type": "manual",
      "until": "2026-09-21T02:29:00.000Z",
      "remaining_s": 715,
      "violations": 1
    }
  ]
}

Block a number

POST/v1/blocksfull key

Blocks one number by hand. Fifteen minutes to begin with; a caller who keeps trying during or after it earns a longer one each time, up to a day. Blocking a number that is already blocked counts as another violation and extends it.

Request body

patternstringrequired: The number, E.164.

Response

patternstring: As normalised.
untilstring: When it lifts.

Errors

invalid_pattern400: Not a number we could parse.
read_only_key403: A cw_read_ key.

RequestShell

BASE=https://api.murusai.com

curl -X POST "$BASE/v1/blocks" \
  -H "Authorization: Bearer $MURUSAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "+12125550143"
  }'

RequestNode

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

const url = new URL("/v1/blocks", BASE);
const res = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "pattern": "+12125550143"
  }),
});
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/blocks",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "pattern": "+12125550143",
    },
)
data = r.json()

201CreatedResponseJSON

{
  "pattern": "+12125550143",
  "until": "2026-09-21T02:29:00.000Z"
}

Lift a block

DELETE/v1/blocks/{pattern}full key

Removes a block, yours or ours, and its violation count with it. The pattern goes in the path, with the plus encoded.

Path parameters

patternstringrequired: The number or stem, URL-encoded: %2B12125550143.

Response

removedboolean: false when there was nothing to remove.

RequestShell

BASE=https://api.murusai.com

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

RequestNode

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

const url = new URL("/v1/blocks/%2B12125550143", 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/blocks/%2B12125550143",
    headers={"Authorization": f"Bearer {KEY}"},
)
data = r.json()

200OKResponseJSON

{ "removed": true }

Blocks

A block

List blocks

Query parameters

Response

Block a number

Request body

Response

Errors

Lift a block

Path parameters

Response

See also