Docs: Improved Namespaces API documentation

Key Improvements Needed in the Namespaces API Documentation

Structure and Organization

Clear overview section explaining what the API does and why you'd use it
Quick start examples for immediate use
Logical flow from simple to complex operations
Common use cases section with practical examples

Technical Clarity

Parameter tables clearly show required vs optional
Response field descriptions explain what each field means
Better examples showing real-world usage patterns
URL encoding explicitly demonstrated for complex paths

Usability Enhancements

Error handling section for troubleshooting
Rate limiting information for planning API usage
Pagination details with practical examples
Related APIs for discovering connected functionality

Proposal

Draft for updated Namespaces API documentation

Overview

The Namespaces API allows you to programmatically query and manage namespaces in GitLab. Namespaces are organizational containers that hold users, groups, and projects.

Use this API to:

List and search namespaces accessible to a user
Retrieve namespace details including member counts and storage usage
Verify namespace name availability
Query namespace hierarchies and relationships

List namespaces

Returns namespaces accessible to the authenticated user. Administrators receive all namespaces in the instance.

GET /namespaces

Parameters

Parameter	Type	Required	Description
`search`	string	No	Filter namespaces by name or path. Case-insensitive partial matching.
`owned_only`	boolean	No	Return only namespaces owned by the current user. Default: `false`
`top_level_only`	boolean	No	Return only root-level namespaces (exclude subgroups). Default: `false` Available in GitLab 16.8+
`full_path_search`	boolean	No	Match search term against full path instead of name only. Default: `false`
`page`	integer	No	Page number for pagination. Default: `1`
`per_page`	integer	No	Results per page (max 100). Default: `20`

Response fields

{
  "id": 1,
  "name": "user1",
  "path": "user1",
  "kind": "user",
  "full_path": "user1",
  "parent_id": null,
  "avatar_url": "https://secure.gravatar.com/avatar/...",
  "web_url": "https://gitlab.example.com/user1",
  "billable_members_count": 1,
  "plan": "ultimate",
  "trial": false,
  "trial_ends_on": null,
  "root_repository_size": 2048576,
  "projects_count": 3
}

Additional fields for GitLab.com

Groups on GitLab.com may include additional billing-related fields:

Field	Type	Description
`max_seats_used`	integer	Maximum seats used in subscription period
`max_seats_used_changed_at`	string	Timestamp of last max seats change
`seats_in_use`	integer	Currently active seats

Note: Billing field visibility may be restricted based on user permissions and instance configuration.

Examples

Search for namespaces containing "frontend":

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces?search=frontend"

List only top-level namespaces you own:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces?owned_only=true&top_level_only=true"

Search full paths for "company/team":

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces?search=company/team&full_path_search=true"

Get namespace details

Retrieve detailed information about a specific namespace.

GET /namespaces/:id

Parameters

Parameter	Type	Required	Description
`id`	integer/string	Yes	Namespace ID or URL-encoded path

Response

Returns a single namespace object with the same fields as the list endpoint.

Examples

Get namespace by ID:

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

Get namespace by path:

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

Get nested namespace by full path:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces/gitlab-org%2Ffrontend"

Note: The path gitlab-org/frontend is URL-encoded as gitlab-org%2Ffrontend.

Check namespace availability

Verify if a namespace name is available for use. Returns suggestions if the name is taken.

GET /namespaces/:namespace/exists

Parameters

Parameter	Type	Required	Description
`namespace`	string	Yes	Proposed namespace path (in URL)
`parent_id`	integer	No	Parent namespace ID for subgroup creation. Omit for top-level.

Response

{
  "exists": false,
  "suggests": []
}

Or if the namespace exists:

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

Examples

Check top-level namespace availability:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces/new-team/exists"

Check subgroup namespace availability:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces/new-subgroup/exists?parent_id=42"

Common Use Cases

Finding all namespaces in a hierarchy

To get all subgroups under a parent namespace:

# First, get the parent namespace ID
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces/acme-corp"

# Then search for namespaces with that parent_id
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces?search=acme-corp&full_path_search=true"

Validating namespace before group creation

# 1. Check if desired name is available
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces/desired-name/exists"

# 2. If not available, use suggested alternatives
# 3. Create group with available namespace name using Groups API

Monitoring namespace storage usage

# Get all owned namespaces with storage information
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces?owned_only=true" \
  | jq '.[] | {name: .name, storage_mb: (.root_repository_size / 1048576)}'

Finding namespaces by plan type

# List all namespaces and filter by plan
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/namespaces?per_page=100" \
  | jq '.[] | select(.plan == "premium")'

Pagination

The Namespaces API uses standard GitLab pagination.

Error Responses

The API returns standard HTTP status codes:

Status Code	Description
200	Success
400	Bad request (invalid parameters)
401	Unauthorized (invalid or missing token)
403	Forbidden (insufficient permissions)
404	Namespace not found
429	Too many requests (rate limited)

Error response format

{
  "message": "404 Namespace Not Found",
  "error": "namespace_not_found"
}

Rate Limiting

The Namespaces API is subject to GitLab's standard rate limiting.

Related APIs

Groups API: Create and manage groups (which are namespaces)
Projects API: Manage projects within namespaces
Users API: Query user namespace information
Members API: Manage namespace members

This revised documentation maintains technical accuracy while being significantly more approachable and useful for developers integrating with the Namespaces API.

Edited Oct 01, 2025 by Christina Lohr