{{< details >}}

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com，私有化部署

{{< /details >}}

使用此 API 与命名空间交互，命名空间是一种用于组织用户和群组的特殊资源类别。有关更多信息，请参阅namespaces。

此 API 使用分页来过滤结果。

列出所有命名空间

{{< history >}}

  • top_level_only 在极狐GitLab 16.8 中引入。

{{< /history >}}

列出当前用户可用的所有命名空间。如果用户是管理员，此端点返回实例中的所有命名空间。

GET /namespaces
属性 类型 必需 描述
search string 否 仅返回名称或路径中包含指定值的命名空间。
owned_only boolean 否 如果为 true，仅返回当前用户的命名空间。
top_level_only boolean 否 在极狐GitLab 16.8 及更高版本中，如果为 true，仅返回顶级命名空间。

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/namespaces"

示例响应：

[
  {
    "id": 1,
    "name": "user1",
    "path": "user1",
    "kind": "user",
    "full_path": "user1",
    "parent_id": null,
    "avatar_url": "https://secure.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
    "web_url": "https://gitlab.example.com/user1",
    "billable_members_count": 1,
    "plan": "ultimate",
    "end_date": null,
    "trial_ends_on": null,
    "trial": false,
    "root_repository_size": 100,
    "projects_count": 3
  },
  {
    "id": 2,
    "name": "group1",
    "path": "group1",
    "kind": "group",
    "full_path": "group1",
    "parent_id": null,
    "avatar_url": null,
    "web_url": "https://gitlab.example.com/groups/group1",
    "members_count_with_descendants": 2,
    "billable_members_count": 2,
    "plan": "ultimate",
    "end_date": null,
    "trial_ends_on": null,
    "trial": false,
    "root_repository_size": 100,
    "projects_count": 3
  },
  {
    "id": 3,
    "name": "bar",
    "path": "bar",
    "kind": "group",
    "full_path": "foo/bar",
    "parent_id": 9,
    "avatar_url": null,
    "web_url": "https://gitlab.example.com/groups/foo/bar",
    "members_count_with_descendants": 5,
    "billable_members_count": 5,
    "end_date": null,
    "trial_ends_on": null,
    "trial": false,
    "root_repository_size": 100,
    "projects_count": 3
  }
]

对于群组所有者或 JihuLab.com 可能返回其他属性：

[
  {
    ...
    "max_seats_used": 3,
    "max_seats_used_changed_at":"2025-05-15T12:00:02.000Z",
    "seats_in_use": 2,
    "projects_count": 1,
    "root_repository_size":0,
    "members_count_with_descendants":26,
    "plan": "free",
    ...
  }
]

获取命名空间的详细信息

获取指定命名空间的详细信息。

GET /namespaces/:id
属性 类型 必需 描述
id integer/string 是 命名空间的 ID 或URL 编码路径。

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/namespaces/2"

示例响应：

{
  "id": 2,
  "name": "group1",
  "path": "group1",
  "kind": "group",
  "full_path": "group1",
  "parent_id": null,
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/group1",
  "members_count_with_descendants": 2,
  "billable_members_count": 2,
  "max_seats_used": 0,
  "seats_in_use": 0,
  "plan": "default",
  "end_date": null,
  "trial_ends_on": null,
  "trial": false,
  "root_repository_size": 100,
  "projects_count": 3
}

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces/group1"

示例响应：

{
  "id": 2,
  "name": "group1",
  "path": "group1",
  "kind": "group",
  "full_path": "group1",
  "parent_id": null,
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/group1",
  "members_count_with_descendants": 2,
  "billable_members_count": 2,
  "max_seats_used": 0,
  "seats_in_use": 0,
  "plan": "default",
  "end_date": null,
  "trial_ends_on": null,
  "trial": false,
  "root_repository_size": 100
}

验证命名空间的可用性

验证指定命名空间是否已存在。如果命名空间确实存在，端点建议替代名称。

GET /namespaces/:namespace/exists
属性 类型 必需 描述
namespace string 是 命名空间的路径。
parent_id integer 否 父命名空间的 ID。如果未指定，仅返回顶级命名空间。

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/namespaces/my-group/exists?parent_id=1"

示例响应：

{
    "exists": true,
    "suggests": [
        "my-group1"
    ]
}