Skip to content
GitmoapAPIBeta
Organizeroles
PATCH/roles/{role_id}

Change a custom role — and with it, everyone who holds it.

update_role
  • role:manage
    A token needs the role:manage scope: Define, change and delete an organization's custom rolesEvery operation this scope unlocks
  • Audited · mutation

    x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

  • Dry run
    Takes dry_run.

Changes the role's slug, name, description, base role or the permissions it adds and removes; send at least one. Every grant and limit using the role changes with it, and the answer lists the permissions gained and lost and how many grants and limits are affected. The same rules as defining a role apply. Only callers who can manage the organization's roles may (its owners, with the built-in roles). With dry_run=true the answer previews the change, and nothing changes.

Parameters

Path
  • role_idRoleId (string · uuid)Role ID
Query
  • dry_runbooleanoptionalSay what would change and for how many grants, and change nothing

Request body

application/json
  • addedarray of string or nulloptional
  • base_roleAccessLevelguestreporterdevelopermaintainerowneror nulloptional
  • descriptionRoleDescription (string) or nulloptional
  • nameRoleName (string) or nulloptional
  • removedarray of string or nulloptional
  • slugEntityName (string) or nulloptional
Request body exampleSynthesized example
{}

Responses

200The role as it now stands and what changed, or a previewapplication/json
  • dry_runboolean
  • grants_affectedinteger · int64Grants of this role, each of which changes with it — on every group and repository they reach.
  • limits_affectedinteger · int64Limits capping someone at this role.
  • permissions_addedarray of stringPermission keys the role holds after the change and did not before.
  • permissions_removedarray of stringPermission keys the role held before the change and does not after.
  • roleCustomRole
    • The CustomRole schema
    • addedarray of stringPermissions added to the base, by key.
    • base_roleAccessLevelguestreporterdevelopermaintainerownerThe built-in role this one starts from, and whose rank it counts as wherever a rank is compared, such as a protected branch's minimum.
    • created_atstring · date-time
    • descriptionstring
    • namestring
    • organization_idGroupId (string · uuid)The organization's top-level group.
    • permissionsarray of stringEverything the role holds: the base, the additions and what they need, less the removals.
    • removedarray of stringPermissions removed from the base, by key.
    • role_idRoleId (string · uuid)
    • slugEntityName (string)
    • updated_atstring · date-time
    • created_byActorSummary or nulloptional
200 exampleSynthesized example
{
"dry_run": false,
"grants_affected": 82,
"limits_affected": 56,
"permissions_added": [
"permissions-added-d118",
"permissions-added-20a1"
],
"permissions_removed": [
"permissions-removed-627c",
"permissions-removed-9592"
],
"role": {
"added": [
"added-f4a6",
"added-51b6"
],
"base_role": "guest",
"created_at": "2026-10-14T03:08:57Z",
"description": "Renders each region as density contours of its operations.",
"name": "payments-api",
"organization_id": "4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69",
"permissions": [
"permissions-9031"
],
"removed": [
"removed-27eb",
"removed-7325"
],
"role_id": "622a852a-aa05-4fed-a98c-85891fd10353",
"slug": "slug-16d5",
"updated_at": "2026-10-16T13:13:28Z",
"created_by": {
"email": "lin@acme.example",
"id": "id-ace0",
"username": "mara",
"avatar_url": "https://gitmoap.example/acme/232eab7c"
}
}
}
400Invalid request, or an unknown permissionapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-45c4",
"message": "Inline scalar newtypes but keep their brand"
}
}
401Authentication requiredapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-abea",
"message": "Pin a page's payload to the build that rendered it"
}
}
403Only the organization's owners change rolesapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-23e6",
"message": "Stream pipeline status into the run header"
}
}
404Role not foundapplication/json
Error codes
  • NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
404 exampleSynthesized example
{
"error": {
"code": "code-75e8",
"message": "Pin a page's payload to the build that rendered it"
}
}
409The organization already has a role with this slugapplication/json
Error codes
  • CONFLICTThe request conflicts with the resource's current state; reason says how
  • LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open
  • ROLE_SLUG_TAKENThe organization already has a role with this slug
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
409 exampleSynthesized example
{
"error": {
"code": "code-16c0",
"message": "Draw the region map from operation density"
}
}
422The role would be based on Owner, hold a permission only Owner may, or keep a permission without what it needsapplication/json
Error codes
  • UNPROCESSABLE_ENTITYThe request is well-formed but asks for something the resource's rules do not allow; reason says which
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
422 exampleSynthesized example
{
"error": {
"code": "code-7342",
"message": "Label every synthesized example"
}
}

CLI

gitmoap roles update-role

  • --role-ididRole ID
  • --dry-runflagoptionalSay what would change and for how many grants, and change nothing
  • --addedjsonoptional
  • --base-roleguest | reporter | developer | maintainer | owneroptional
  • --descriptionstringoptional
  • --namestringoptional
  • --removedjsonoptional
  • --slugstringoptional

Used in these guides