Skip to content
GitmoapAPIBeta
Organizegroups
POST/admin/groups/{group_id}/reclaim-name

Reclaim an organization's name (platform admin)

reclaim_group_name
  • namespace_admin:manage
    A token needs the namespace_admin:manage scope: Reclaim an organization's name and hold it for another (platform admins)Granted by write_api.Every operation this scope unlocks
  • Audited · mutation

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

Takes a name from an organization that impersonates somebody, or whose name infringes a trademark or another right somebody holds in it. The organization is renamed — to new_name, or to renamed- followed by eight letters and digits — and everything in it moves with it; the name it held is held back for good, for the organization named in hold_for_group_id, which may then rename itself to it. The organization's owners are sent the reasons before the name is taken. Only platform administrators, in a signed-in session, reclaim names.

Parameters

Path
  • group_idGroupId (string · uuid)The organization whose name is reclaimed

Request body

application/json
  • noteReclaimNote (string)What the reclaim rests on, kept with the record of it.
  • reasonReclaimReasonimpersonationinfringementWhy the name is reclaimed.
  • hold_for_group_idGroupId (string · uuid) or nulloptionalThe organization the released name is kept for, which may then rename itself to it. Omitted, the name is kept for nobody.
  • new_nameEntityName (string) or nulloptionalThe name the organization is given instead. Omitted, it is renamed to renamed- followed by eight letters and digits.
Request body exampleSynthesized example
{
"note": "note-40d7",
"reason": "impersonation"
}

Responses

200Name reclaimed and the organization renamedapplication/json
  • groupRepositoryGroupThe organization, under the name it was given.
    • The RepositoryGroup schema
    • created_atstring
    • created_byUserId (string · uuid)
    • full_pathFullPath (string)
    • group_idGroupId (string · uuid)
    • group_nameEntityName (string)
    • updated_atstring
    • visibilityVisibilitypublicinternalprivate
    • ancestor_group_idsarray of GroupId (string · uuid)optional
    • avatarstring or nulloptional
    • descriptionstring or nulloptional
    • display_namestring or nulloptional
    • parent_group_idGroupId (string · uuid) or nulloptional
  • reasonReclaimReasonimpersonationinfringementWhy the name was reclaimed.
  • reclaimed_atstringWhen the name was reclaimed.
  • released_nameEntityName (string)The name it no longer holds, now held back for good.
  • held_for_group_idGroupId (string · uuid) or nulloptionalThe organization the released name is kept for, if any.
200 exampleSynthesized example
{
"group": {
"created_at": "2026-10-11T01:56:12Z",
"created_by": "c9d8e7f6-a5b4-4c3d-9e2f-1a0b9c8d7e6f",
"full_path": "acme/payments-api",
"group_id": "4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69",
"group_name": "payments-api",
"updated_at": "2026-10-15T01:43:08Z",
"visibility": "public",
"ancestor_group_ids": [
"4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69",
"4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69"
],
"avatar": "avatar-baa0",
"description": "Renders each region as density contours of its operations.",
"display_name": "Mara Okafor",
"parent_group_id": "4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69"
},
"reason": "impersonation",
"reclaimed_at": "2026-10-10T04:53:17Z",
"released_name": "payments-api",
"held_for_group_id": "4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69"
}
400The group is not an organization, or the request is invalidapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • NOT_AN_ORGANIZATIONOnly an organization — a top-level group — has teams and custom roles, and a name that can be reclaimed or held for 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.
400 exampleSynthesized example
{
"error": {
"code": "code-d4d6",
"message": "Label every synthesized example"
}
}
401Unauthenticated — no credential, or an invalid oneapplication/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-8600",
"message": "Pin a page's payload to the build that rendered it"
}
}
403Not a platform administrator, or the new name is reservedapplication/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
  • NAME_RESEMBLES_RESERVEDThe name looks like a name reserved for another organization; prove that organization's domain, or choose another name
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • RESERVED_NAMESPACEThe name is reserved — for the platform, or for the organization that owns the domain the message names
  • 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-532d",
"message": "Inline scalar newtypes but keep their brand"
}
}
404Group 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-2978",
"message": "Draw the region map from operation density"
}
}
409The new name is taken or held backapplication/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
  • NAME_RETIREDAnother organization gave the name up recently, or published under it, so it is held back; choose another name
  • 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-36e1",
"message": "Draw the region map from operation density"
}
}

CLI

gitmoap groups reclaim-name

  • --group-ididThe organization whose name is reclaimed (id or group path)
  • --hold-for-group-idstringoptional
  • --new-namestringoptional
  • --notestringWhat the reclaim rests on, kept with the record of it.
  • --reasonimpersonation | infringementWhy the name is reclaimed.

Used in these guides