Create role
Create role
- Method
- POST
- Path
https://api.returning.ai / roles
Authentication#
- Header
Authorization: Bearer <API_KEY>
Behaviour#
- Legacy category
This endpoint is retained for compatibility, historical admin tooling, or test workflows. Do not use it as the default choice for new integrations unless the backend team confirms this exact route is still supported for your community.
- What it is for
Create role.
- How to use it
Send a POST request to
/roleswith the documented body, query parameters, headers, or multipart fields. Prefer the newer authenticated/v1/...integration API where available.- Successful response
HTTP 2xx. Older endpoints may return a legacy response envelope or a resource-specific payload rather than the newer
{ status, message, data }wrapper.- Common error states
400invalid request body, query, ObjectId, pagination, file format, or missing required field.401missing, invalid, expired, or insufficient API key/token.403key is valid but cannot access this community/channel/user/resource, where supported by the service.404route or target resource was not found. Several legacy root routes return404onhttps://api.returning.ai; confirm with Returning.AI before using them.409duplicate or conflicting state for create/update operations, where applicable.500unexpected Returning.AI service error.
- Legacy status
Compatibility endpoint retained for older integrations. Do not use this endpoint for new integrations unless Returning.AI specifically tells you to maintain a legacy flow. Prefer the current
/v1/...endpoint in the matching non-Legacy category when one exists.- Source-backed clarification
These are compatibility endpoints using older server/role terminology. Use them only when maintaining an existing integration. For new public docs and integrations, prefer community/user permission language and scoped API-key permissions.
Request#
Headers#
Body#
Eg"blue"
Eg"Manager 2"
Eg1
Eg{ ... }
Egfalse
Egfalse
Egfalse
Egfalse
Egfalse
Egfalse
Egfalse
Egfalse
Eg{ ... }
Egtrue
Egtrue
Egtrue
Egtrue
Egtrue
curl --request POST \
--url https://api.returning.ai/roles \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"class": "blue",
"title": "Manager 2",
"order": 1,
"server_permissions": {
"server_administrator": false,
"allow_dm": false,
"create_invite": false,
"warn_members": false,
"suspend_members": false,
"ban_members": false,
"broadcast_messages": false,
"overwrite_language": false
},
"channel_permissions": {
"post_messages": true,
"attach_files": true,
"allow_mentions": true,
"manage_messages": true,
"pinable": true,
"share_links": true,
"share_Attachments": true
}
}'
Response#
Eg{ ... }
Egtrue
Eg"Role has been created successfully"
Eg"Role has been created successfully"
Eg{ ... }
Eg1
Egtrue
Eg"Moderator"
Eg"Role with permissions to moderate the server"
Eg{ ... }
Egtrue
Egtrue
Egtrue
Egtrue
Egtrue
Egtrue
Egtrue
Eg"{_id}"
Eg{ ... }
Egtrue
Egtrue
Egtrue
Egtrue
Egtrue
Egtrue
Eg"{_id}"
Eg"red"
Eg"{_id}"
Eg"2024-08-06T03:56:39.162Z"
Eg"2024-08-06T03:56:39.162Z"
Eg0
{
"meta": {
"success": true,
"message": "Role has been created successfully",
"devMessage": "Role has been created successfully"
},
"body": {
"order": 1,
"billable": true,
"title": "Moderator",
"description": "Role with permissions to moderate the server",
"server_permissions": {
"allow_dm": true,
"create_invite": true,
"kick_members": true,
"ban_members": true,
"manage_roles": true,
"manage_channels": true,
"server_administrator": true,
"_id": "{_id}"
},
"channel_permissions": {
"view_message_history": true,
"manage_messages": true,
"allow_mentions": true,
"post_messages": true,
"post_analysis": true,
"attach_files": true,
"_id": "{_id}"
},
"class": "red",
"serverId": "{_id}",
"_id": "{_id}",
"createdAt": "2024-08-06T03:56:39.162Z",
"updatedAt": "2024-08-06T03:56:39.162Z",
"__v": 0
}
}
Errors#
Fix the request03
Fix the data01
Retry with backoff01
{
"status": "fail",
"message": "Invalid request. Check required parameters, body fields, file format, pagination values, and ObjectId values."
}