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.

Creates a new role in the system. The roleName must be unique — attempting to create a role with a name that already exists (case-insensitive) returns 409 Conflict. On success, the full role record including its auto-generated idRole is returned. After a successful creation, a data:changed Socket.IO event is broadcast to all connected clients so their UI can refresh the roles list.

​
Authentication

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

​
Request

Method: POST Path: /api/v1/roles

​
Headers

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

​
Body

​
roleName
string
required
The unique name for the role. Must be between 2 and 50 characters. The uniqueness check is case-insensitive.
​
description
string
Optional human-readable description explaining the role’s purpose. Stored as null if omitted.
Example Request Body
{
  "roleName": "Moderator",
  "description": "Can review and approve user-submitted content"
}

​
Response

​
201 Created

Returns the newly created role object.
​
success
boolean
Always true for successful responses.
​
message
string
Human-readable status message. Value: "Rol creado exitosamente".
​
data
object
The created role record.
Example Response
{
  "success": true,
  "message": "Rol creado exitosamente",
  "data": {
    "idRole": 4,
    "roleName": "Moderator",
    "description": "Can review and approve user-submitted content"
  }
}

​
Error Responses

StatusDescription
400 Bad RequestValidation failed — roleName is missing, too short, or too long.
401 UnauthorizedMissing or invalid JWT token.
403 ForbiddenAuthenticated user’s role lacks the POST /api/v1/roles permission.
409 ConflictA role with the given roleName already exists (case-insensitive match).
409 Conflict
{
  "success": false,
  "message": "El rol 'Moderator' ya existe",
  "data": null
}

​
Code Example

cURL
curl -X POST http://localhost:3000/api/v1/roles \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "roleName": "Moderator",
    "description": "Can review and approve user-submitted content"
  }'

​
Socket.IO Events

On success, the server emits the following events:
EventTargetOperationStatus sequence
operation:progressRequesting socketroles:createstart → processing → success
data:changedAll connected clientsroles:createBroadcast with the new 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