Create a ban

POST

/v1/server/bans

curl --request POST \
  --url https://app.mondochat.io/v1/server/bans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Mondochat-App-Id: <Mondochat-App-Id>' \
  --data '{ "expires_at": "2026-12-01T00:00:00Z", "external_id": "alice", "reason": "Spam" }'

Bans one of your users by external_id, or an IPv4 or IPv6 range by cidr; give one of them. A ban may expire. Takes the app id and the server secret, and an Idempotency-Key header. A banned user is refused with 403 banned at session exchange and refresh, conversation open, message send, call start, call token and upload; the problem carries reason temporary when the ban expires. A banned user is sent session.revoked. Bans are cached for 60 seconds. Sends the ban.created webhook. See https://docs.mondochat.io/guides/safety/.

Authorizations

• app_id
• server_secret

Parameters

Header Parameters

Idempotency-Key

Any of:

string

string

>= 1 characters <= 255 characters

null

null

Request Body^required

Media typeapplication/json

ServerBanCreate

A ban your server creates on one of your users or on an address range.

object

cidr

Any of:

string

string format: ipvanynetwork

null

null

expires_at

Any of:

string

string format: date-time

null

null

external_id

Any of:

string

string

/^[A-Za-z0-9._:@-]{1,128}$/

null

null

reason

required

Reason

Why the ban is made.

string

>= 1 characters <= 1000 characters

Responses

200

Successful Response

Media typeapplication/json

Ban

A ban on a user or an address range.

object

cidr

Any of:

string

string

null

null

created_at

required

Created At

When the ban was made.

string format: date-time

created_by

Any of:

string

string

null

null

created_by_name

Any of:

string

string

null

null

expires_at

Any of:

string

string format: date-time

null

null

external_id

Any of:

string

string

null

null

id

required

Id

The ban’s id.

string format: uuid

lifted_at

Any of:

string

string format: date-time

null

null

reason

required

Reason

Why the ban was made.

string

user_id

Any of:

string

string format: uuid

null

null

Example

{
  "created_at": "2026-11-01T09:30:00Z",
  "expires_at": "2026-12-01T00:00:00Z",
  "external_id": "alice",
  "id": "0199d6a0-6000-7000-8000-000000000001",
  "reason": "Spam",
  "user_id": "0199d6a0-1000-7000-8000-000000000001"
}

4XX

Problem

Media typeapplication/problem+json

An RFC 9457 problem: the body of every error answer.

object

code

required

The stable error code to branch on, such as policy_denied.

string

detail

What went wrong this time, when there is more to say.

string | null

errors

For validation, one entry per invalid field.

Array<object>

One invalid field.

object

loc

The path to the field.

array

msg

What is wrong with it.

string

instance

The path of the request.

string

reason

For policy_denied and limit_reached, the rule or limit that refused the request; for forbidden, a short cause such as you_blocked; for banned, temporary when the ban expires.

string

status

required

The HTTP status code.

integer

title

required

A short summary of the problem.

string

type

required

A URL that names the problem, https://app.mondochat.io/problems/<code>.

string

Example

{
  "code": "policy_denied",
  "detail": null,
  "instance": "/v1/conversations/0199d6a0-2000-7000-8000-000000000001",
  "reason": "pins",
  "status": 403,
  "title": "Policy denied",
  "type": "https://app.mondochat.io/problems/policy_denied"
}