Returning.AIDevelopers
v1

API reference / Legacy / Roles & Permissions

.md

Update role

Update role

Last updated 26 Sep 2026API v1

Method
PUT
Path
https://api.returning.ai/roles/{id}

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

Update role.

How to use it

Send a PUT request to /roles/{id} with 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
  • 400 invalid request body, query, ObjectId, pagination, file format, or missing required field.
  • 401 missing, invalid, expired, or insufficient API key/token.
  • 403 key is valid but cannot access this community/channel/user/resource, where supported by the service.
  • 404 route or target resource was not found. Several legacy root routes return 404 on https://api.returning.ai; confirm with Returning.AI before using them.
  • 409 duplicate or conflicting state for create/update operations, where applicable.
  • 500 unexpected 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#

Path parameters#

id#stringREQUIRED
Resource ID. For bulk update status/details this should be the bulk job ObjectId.

Eg682d61dfd843de46566c9eab

Headers#

Authorization#stringREQUIRED
API key.

RuleBearer <API_KEY>

x-api-key#stringREQUIRED
Legacy server API key header. Prefer Authorization: Bearer <API_KEY> for /v1/... integration APIs.
Content-Type#stringREQUIRED
Request body format.

Ruleapplication/json

Body#

class#stringREQUIRED

Eg"blue"

title#stringREQUIRED

Eg"Manager 2"

order#integerREQUIRED

Eg1

billable#booleanREQUIRED

Egfalse

server_permissions#objectREQUIRED

Eg{ ... }

server_administrator#booleanREQUIRED

Egfalse

allow_dm#booleanREQUIRED

Egfalse

create_invite#booleanREQUIRED

Egfalse

warn_members#booleanREQUIRED

Egfalse

suspend_members#booleanREQUIRED

Egfalse

ban_members#booleanREQUIRED

Egfalse

broadcast_messages#booleanREQUIRED

Egfalse

overwrite_language#booleanREQUIRED

Egfalse

channel_permissions#objectREQUIRED

Eg{ ... }

post_messages#booleanREQUIRED

Egtrue

attach_files#booleanREQUIRED

Egtrue

allow_mentions#booleanREQUIRED

Egtrue

manage_messages#booleanREQUIRED

Egtrue

pinable#booleanREQUIRED

Egtrue

share_Attachments#booleanREQUIRED

Egtrue

curl --request PUT \
  --url 'https://api.returning.ai/roles/<id>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "class": "blue",
    "title": "Manager 2",
    "order": 1,
    "billable": false,
    "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#

meta#objectALWAYS

Eg{ ... }

success#booleanALWAYS

Egtrue

message#stringALWAYS

Eg"Role has been updated successfully"

devMessage#stringALWAYS

Eg"Role has been updated successfully"

body#objectALWAYS

Eg{ ... }

_id#stringALWAYS

Eg"{_id}"

order#integerALWAYS

Eg2

billable#booleanALWAYS

Egfalse

title#stringALWAYS

Eg"Moderator"

description#stringALWAYS

Eg"Role with permissions to moderate the server"

server_permissions#objectALWAYS

Eg{ ... }

allow_dm#booleanALWAYS

Egtrue

create_invite#booleanALWAYS

Egtrue

kick_members#booleanALWAYS

Egtrue

ban_members#booleanALWAYS

Egtrue

manage_roles#booleanALWAYS

Egtrue

manage_channels#booleanALWAYS

Egtrue

server_administrator#booleanALWAYS

Egtrue

_id#stringALWAYS

Eg"66a27b91fe1c879712142894"

channel_permissions#objectALWAYS

Eg{ ... }

view_message_history#booleanALWAYS

Egtrue

manage_messages#booleanALWAYS

Egtrue

allow_mentions#booleanALWAYS

Egtrue

post_messages#booleanALWAYS

Egtrue

post_analysis#booleanALWAYS

Egtrue

attach_files#booleanALWAYS

Egtrue

_id#stringALWAYS

Eg"{_id}"

class#stringALWAYS

Eg"blue"

createdAt#stringALWAYS

Eg"2024-07-25T16:17:27.299Z"

updatedAt#stringALWAYS

Eg"2024-07-25T16:21:37.761Z"

__v#integerALWAYS

Eg0

{
  "meta": {
    "success": true,
    "message": "Role has been updated successfully",
    "devMessage": "Role has been updated successfully"
  },
  "body": {
    "_id": "{_id}",
    "order": 2,
    "billable": false,
    "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": "66a27b91fe1c879712142894"
    },
    "channel_permissions": {
      "view_message_history": true,
      "manage_messages": true,
      "allow_mentions": true,
      "post_messages": true,
      "post_analysis": true,
      "attach_files": true,
      "_id": "{_id}"
    },
    "class": "blue",
    "serverId": "{_id}",
    "createdAt": "2024-07-25T16:17:27.299Z",
    "updatedAt": "2024-07-25T16:21:37.761Z",
    "__v": 0
  }
}

Errors#

Fix the request03

400Fix the request
Invalid request. Check required parameters, body fields, file format, pagination values, and ObjectId values.
401Fix the request
Missing, invalid, expired, or insufficient API key/token. Older permission middleware may also return 401 for missing permissions.
403Fix the request
The API key is valid but is not allowed to access this community, channel, user, or resource.

Fix the data02

404Fix the data
The requested resource, route, community, channel, user, API key, status, or job was not found.
409Fix the data
The request conflicts with an existing resource or immutable state, such as a duplicate slug/key/name or an already-processed record.

Retry with backoff01

500Retry with backoff
Unexpected Returning.AI service error.
{
  "status": "fail",
  "message": "Invalid request. Check required parameters, body fields, file format, pagination values, and ObjectId values."
}

Next step#

Delete roleDELETE/roles/{id}