Get project custom roles¶

GET /api/v5/repos/{owner}/{repo}/customized_roles

Retrieves the custom role list of the specified repository (project), returning an array of role objects with the role name, permission level, member count, creation time, and update time.

Supported access tokens¶

AtomGit user access tokens

Anonymous access allowed¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Namespace address to which the repository belongs (address path of the enterprise, organization, or user)
`repo`	path	string	Yes	Repository path (path)
`access_token`	query	string	Yes	User authorization code

Response parameters¶

Field	Type	Always returned	Nullable	Description
`role_id`	string	Yes	No	Role ID
`access_level`	integer	Yes	No	Permission level (the example value is `15`)
`role_name`	string	Yes	No	Role name
`role_chinese_name`	string	Yes	No	Role name in Chinese
`role_description`	string	Yes	No	Role description
`role_type`	string	Yes	No	Role type; this endpoint always returns `project-customized`
`member_count`	integer	Yes	No	Number of members with the role
`created_at`	string	Yes	No	Creation time (format such as `2024-04-17 08:00`)
`updated_at`	string	Yes	No	Update time (format such as `2024-04-17 08:00`)
`role_from`	string	Yes	—	Role source (defined in the response DTO; the meaning of its values could not be determined)

The endpoint returns an array of custom role objects; the table above describes the fields of each array element (a single role object).

Error response¶

This endpoint requires authentication and project access rights; it returns the corresponding error when authentication fails or permission is insufficient. The following are common error response examples (error field names follow what the backend actually returns):

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

403 Access forbidden

{
  "error": "forbidden",
  "message": "No permission to access this project"
}

404 Resource does not exist

{
  "error": "not_found",
  "message": "Repository does not exist"
}

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`401`	Authentication required (Requires authentication)
`403`	Access forbidden (Forbidden)
`404`	Request path or resource does not exist (Not found)

Request example¶

Parameter notes¶

<owner> — replace with the namespace address to which the repository belongs (address path of the enterprise, organization, or user); <repo> — replace with the repository path (path); <token> — replace with your AtomGit user access token.

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/customized_roles?access_token=<token>' \
  -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browsers)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/customized_roles?access_token=<token>",
  {
    headers: {
      "Accept": "application/json",
    },
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.get(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/customized_roles",
    params={"access_token": "<token>"},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

[
  {
    "role_id": "e6cd76d6c82f46c78c71fd7f67eaf3bf",
    "access_level": 15,
    "role_name": "Test role",
    "role_chinese_name": "Test role",
    "role_description": "Test role",
    "role_type": "project-customized",
    "member_count": 1,
    "created_at": "2024-04-17 08:00",
    "updated_at": "2024-04-17 08:00"
  }
]

Error codes¶

Error code	Description
`401`	Unauthenticated or invalid credentials (missing or invalid access credentials)
`403`	Access forbidden (no permission)
`404`	Request path or resource does not exist
`400`	Invalid parameters or the request cannot be parsed
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc