Update a custom organization role

PATCH

organization

roles

{id}

curl --request PATCH \
  --url https://api.runpod.io/v2/organization/roles/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Pod operator"
}
'

{
  "id": "cmcustomrole0001",
  "name": "Pod operator",
  "type": "custom",
  "capabilities": [
    "POD:USE",
    "POD:VIEW"
  ],
  "createdAt": "2026-10-01T09:00:00Z",
  "updatedAt": "2026-10-03T09:00:00Z"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "resource not found"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

{
  "title": "Request Entity Too Large",
  "status": 413,
  "detail": "Request body exceeds the 1048576 byte limit."
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

Authorizations

Authorization

string

header

required

Runpod API key authentication. Generate an API key in the Runpod console and send it in the Authorization header as Bearer <api_key>. Keys are scoped to the permissions granted when created; requests may return 403 when a valid key lacks access to the requested resource or action.

Console sessions (Clerk JWTs) act for the signed-in user. To act for a team instead, also send X-Team-Id: <team_id>; it applies only when the user owns or belongs to that team, otherwise the request runs against the user's own account. API keys created inside a team already act for that team and do not need the header.

Path Parameters

string

required

Role identifier

Body

application/json

The fields to change; omitted fields are unchanged. capabilities replaces the role's whole grant set rather than adding to it.

name

string

Display name, 1–191 characters with at least one non-whitespace character. Leading and trailing whitespace is trimmed. It must be unique within the organization and cannot be a built-in role's name.

Required string length: 1 - 191

Pattern: [^\t-\r   -     　]

Example:

"Pod viewer"

capabilities

string[]

What the role grants, as FAMILY:VERB capabilities from GET /v2/organization/roles/capabilities. The caller must hold every capability it lists.

Minimum array length: 1

Pattern: ^[A-Z0-9_]+:[A-Z0-9_]+$

Example:

["POD:VIEW"]

Response

Option 1
Option 2

A role an organization member or invite can hold: one of Runpod's built-in roles, or a custom role the organization defined.

string

required

Role ID, builtin: followed by the role's key.

Example:

"builtin:dev"

name

string

required

Display name.

Example:

"Developer"

type

enum<string>

required

Always builtin for this variant.

Available options:

builtin

capabilities

string[]

required

What the role grants, as FAMILY:VERB capabilities, sorted. A member's effective access can also include account-level access that no role grants.

Example:

["POD:CREATE", "POD:VIEW"]

Last modified on November 3, 2026

curl --request PATCH \
  --url https://api.runpod.io/v2/organization/roles/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Pod operator"
}
'

{
  "id": "cmcustomrole0001",
  "name": "Pod operator",
  "type": "custom",
  "capabilities": [
    "POD:USE",
    "POD:VIEW"
  ],
  "createdAt": "2026-10-01T09:00:00Z",
  "updatedAt": "2026-10-03T09:00:00Z"
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "request could not be processed"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing bearer token"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "access denied"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "resource not found"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

{
  "title": "Request Entity Too Large",
  "status": 413,
  "detail": "Request body exceeds the 1048576 byte limit."
}

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed."
}

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded for the minute window"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "pod not found",
  "errors": [
    "$: additional properties 'bogus' not allowed"
  ]
}

API v2

Organization

Account

Pods

Clusters

Serverless

Templates

Network Volumes

Global Volumes

Registries

Catalog

Cost Centers

Audit Logs

Billing

Authorizations

Path Parameters

Body

Response