Documentation Menu

Moderation tools including bans, blocks, and audit logging. Most endpoints require admin or owner role.

Ban a user from workspace

POST /workspaces/{wid}/bans/create

Requires authentication.

Ban a user from the workspace. Only admins and owners can ban. Cannot ban users with equal or higher role rank (admins cannot ban other admins or the owner). Self-banning is prohibited. Specify duration_hours for a temporary ban (1-8760 hours), or omit for a permanent ban. Set hide_messages to true to hide the banned user's messages from all queries.

Errors:

  • 400: Self-ban attempted, or target user is not a workspace member.
  • 403: Caller lacks admin/owner role, or target has equal or higher role rank.
  • 404: Workspace not found.
  • 409: User is already banned in this workspace.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
  "reason": "Repeated spam",
  "hide_messages": false,
  "duration_hours": 24
}

Responses

200 User banned

{
  "ban": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
    "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "banned_by": "string",
    "reason": "Repeated spam",
    "hide_messages": true,
    "expires_at": "2025-01-15T09:30:00Z",
    "created_at": "2025-01-15T09:30:00Z"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

409 User already banned

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

Unban a user from workspace

POST /workspaces/{wid}/bans/remove

Requires authentication.

Remove an active ban for a user in the workspace, restoring their access. Only admins and owners can unban users. The user's membership is not automatically restored; they must rejoin or be re-invited.

Errors:

  • 401: Not authenticated.
  • 403: Caller lacks admin/owner role.
  • 404: Workspace not found or no active ban exists for the specified user.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V"
}

Responses

200 User unbanned

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

List active bans in workspace

POST /workspaces/{wid}/bans/list

Requires authentication.

List all currently active bans in the workspace with cursor-based pagination. Only admins and owners can view the ban list. Each ban includes the banned user's display name and email. Expired temporary bans are excluded from results.

Errors:

  • 401: Not authenticated.
  • 403: Caller lacks admin/owner role.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "cursor": "eyJpZCI6IjAxSkVYQU1QTEUifQ",
  "limit": 50
}

Responses

200 List of active bans

{
  "bans": [
    {
      "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
      "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "banned_by": "string",
      "reason": "Repeated spam",
      "hide_messages": true,
      "expires_at": "2025-01-15T09:30:00Z",
      "created_at": "2025-01-15T09:30:00Z",
      "user_display_name": "Alice Chen",
      "user_email": "alice@example.com",
      "user_avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
      "banned_by_name": "Bob Martinez"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6IjAxSkVYQU1QTEUifQ"
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

Block a user in workspace

POST /workspaces/{wid}/blocks/create

Requires authentication.

Block a user within the workspace scope. Blocking is workspace-scoped, meaning the block only applies within this workspace. Blocked users' messages are hidden from the blocker in message queries. Any authenticated workspace member can block another member. Self-blocking is not allowed.

Errors:

  • 400: Self-block attempted, or target user is not a workspace member.
  • 401: Not authenticated.
  • 403: Caller is not a member of the workspace.
  • 404: Workspace or target user not found.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V"
}

Responses

200 User blocked

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Unblock a user in workspace

POST /workspaces/{wid}/blocks/remove

Requires authentication.

Remove a block on a user within the workspace scope. Only the user who created the block can remove it. After unblocking, the previously blocked user's messages will be visible again in message queries.

Errors:

  • 401: Not authenticated.
  • 403: Caller is not a member of the workspace.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "user_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V"
}

Responses

200 User unblocked

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

List blocked users in workspace

GET /workspaces/{wid}/blocks/list

Requires authentication.

List all users the caller has blocked within this workspace. Returns only the caller's own blocks (users cannot see other members' block lists). Each entry includes the blocked user's display name and email.

Errors:

  • 401: Not authenticated.
  • 403: Caller is not a member of the workspace.

Parameters

Name In Type Description
wid path string Workspace ID

Responses

200 List of blocked users

{
  "blocks": [
    {
      "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
      "blocker_id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "blocked_id": "01JQ3KMS4WTVY6BN8FRCJD2HAQ",
      "created_at": "2025-01-15T09:30:00Z",
      "display_name": "Alice Chen",
      "email": "alice@example.com",
      "avatar_url": "/files/01JQ3KMT6B/download?sig=abc"
    }
  ]
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

List moderation audit log

POST /workspaces/{wid}/moderation-log/list

Requires authentication.

List the moderation audit log for the workspace with cursor-based pagination. Records all moderation actions including bans, unbans, and role changes. Only admins and owners can view the audit log. Each entry includes the acting user's display name and email for accountability.

Errors:

  • 401: Not authenticated.
  • 403: Caller lacks admin/owner role.

Parameters

Name In Type Description
wid path string Workspace ID

Request body 

{
  "cursor": "eyJpZCI6IjAxSkVYQU1QTEUifQ",
  "limit": 50
}

Responses

200 List of moderation log entries

{
  "entries": [
    {
      "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "workspace_id": "01JQ3KMP2RQHYJ5ZV8NMWCX4ET",
      "actor_id": "01JQ3KMS4WTVY6BN8FRCJD2HAQ",
      "action": "ban_user",
      "target_type": "user",
      "target_id": "01JQ3KMS4WTVY6BN8FRCJD2HAQ",
      "metadata": {},
      "created_at": "2025-01-15T09:30:00Z",
      "actor_display_name": "Bob Martinez",
      "actor_avatar_url": "string",
      "target_display_name": "Carol Williams"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6IjAxSkVYQU1QTEUifQ"
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}