Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheSerchCp/SEAM-API/llms.txt

Use this file to discover all available pages before exploring further.

Updates one or both fields (roleName, description) of an existing role identified by its numeric idRole path parameter. All body fields are optional — only fields present in the request body are applied. If roleName is provided and differs from the current value, its uniqueness is validated (case-insensitive) before saving. The full updated record is returned. After a successful update, a data:changed Socket.IO event is broadcast to all connected clients.

​
Authentication

Requires a valid JWT and the PUT /api/v1/roles/:idRole permission assigned to the caller’s role.

​
Request

Method: PUT Path: /api/v1/roles/:idRole

​
Headers

​
Authorization
string
required
Bearer token obtained from the login endpoint. Format: Bearer <token>
​
Content-Type
string
required
Must be application/json.

​
Path Parameters

​
idRole
string
required
The numeric ID of the role to update. Must match ^\d+$ (digits only, no decimals or negative values).

​
Body

All body fields are optional. At least one should be provided to make a meaningful request.
​
roleName
string
New name for the role. Must be between 2 and 50 characters and must not conflict with an existing role name (case-insensitive).
​
description
string
New description for the role. Pass an empty string to clear the current description.
Example Request Body
{
  "roleName": "SuperModerator",
  "description": "Elevated moderation privileges including ban capability"
}

​
Response

​
200 OK

Returns the full updated role object as it now exists in the database.
​
success
boolean
Always true for successful responses.
​
message
string
Human-readable status message. Value: "Rol actualizado exitosamente".
​
data
object
The updated role record fetched from the database after the update is applied.
Example Response
{
  "success": true,
  "message": "Rol actualizado exitosamente",
  "data": {
    "idRole": 4,
    "roleName": "SuperModerator",
    "description": "Elevated moderation privileges including ban capability"
  }
}

​
Error Responses

StatusDescription
400 Bad RequestidRole is not numeric, or roleName fails length validation.
401 UnauthorizedMissing or invalid JWT token.
403 ForbiddenAuthenticated user’s role lacks the PUT /api/v1/roles/:idRole permission.
404 Not FoundNo role exists with the given idRole.
409 ConflictThe provided roleName is already used by a different role.
404 Not Found
{
  "success": false,
  "message": "Rol con id 99 no encontrado",
  "data": null
}
409 Conflict
{
  "success": false,
  "message": "El nombre 'Admin' ya está en uso",
  "data": null
}

​
Code Example

cURL
curl -X PUT http://localhost:3000/api/v1/roles/4 \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "roleName": "SuperModerator",
    "description": "Elevated moderation privileges including ban capability"
  }'

​
Socket.IO Events

On success, the server emits the following events:
EventTargetOperationStatus sequence
operation:progressRequesting socketroles:updatestart → processing → success
data:changedAll connected clientsroles:updateBroadcast with the updated role object
Clients listening to data:changed can use the initiatorSocketId field in the payload to skip redundant UI updates if they already know the result from the HTTP response.

Build docs developers (and LLMs) love

Get started for freeTalk to us