---
title: "Closing down - Create a custom role"
method: POST
path: "/orgs/{org}/custom_roles"
tags: ["orgs"]
deprecated: true
---

# Closing down - Create a custom role

`POST /orgs/{org}/custom_roles`

> **Deprecated.**

> [!WARNING]
> **Closing down notice:** This operation is closing down and will be removed after September 6, 2023. Use the "[Create a custom repository role](https://docs.github.com/enterprise-cloud@latest/rest/orgs/custom-roles#create-a-custom-repository-role)" endpoint instead.

Creates a custom repository role that can be used by all repositories owned by the organization. For more information on custom repository roles, see "[About custom repository roles](https://docs.github.com/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles)."

The authenticated user must be an administrator for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.

## Path parameters

- `org` string, required

## Request body

- OrganizationCustomRepositoryRoleCreateSchema
  - `name` string, required — The name of the custom role.
  - `description` string, nullable — A short description about who this role is for or what permissions it grants.
  - `base_role` 'read' | 'triage' | 'write' | 'maintain', required — The system role from which this role inherits permissions.
  - `permissions` string[], required — A list of additional permissions included in this role.

## Response `201`

Response

- OrganizationCustomRepositoryRole — Custom repository roles created by organization owners
  - `id` integer, required — The unique identifier of the custom role.
  - `name` string, required — The name of the custom role.
  - `description` string, nullable — A short description about who this role is for or what permissions it grants.
  - `base_role` 'read' | 'triage' | 'write' | 'maintain', required — The system role from which this role inherits permissions.
  - `permissions` string[], required — A list of additional permissions included in this role.
  - `organization` SimpleUser, required — A GitHub user.
    - `name` string, nullable
    - `email` string, nullable
    - `login` string, required
    - `id` integer, required
    - `node_id` string, required
    - `avatar_url` string, uri, required
    - `gravatar_id` string, nullable, required
    - `url` string, uri, required
    - `html_url` string, uri, required
    - `followers_url` string, uri, required
    - `following_url` string, required
    - `gists_url` string, required
    - `starred_url` string, required
    - `subscriptions_url` string, uri, required
    - `organizations_url` string, uri, required
    - `repos_url` string, uri, required
    - `events_url` string, required
    - `received_events_url` string, uri, required
    - `type` string, required
    - `site_admin` boolean, required
    - `starred_at` string
    - `user_view_type` string
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `404` — Resource not found
- `422` — Validation failed, or the endpoint has been spammed.

---

[API](https://skmtc.net/github/apis/github-v3-rest-api-3.md) · [All operations](https://skmtc.net/github/apis/github-v3-rest-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/github/github-v3-rest-api-3/versions/dc0584ac4e13/schema)