Custom Attributes API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

Every API call to custom attributes must be authenticated as administrator.

Custom attributes are currently available on users, groups, and projects, which is referred to as “resource” in this documentation.

List custom attributes

Get all custom attributes on a resource.

Copy to clipboard
GET /users/:id/custom_attributes
GET /groups/:id/custom_attributes
GET /projects/:id/custom_attributes
Attribute Type Required Description
id integer yes The ID of a resource
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/custom_attributes"

Example response:

Copy to clipboard
[
   {
      "key": "location",
      "value": "Antarctica"
   },
   {
      "key": "role",
      "value": "Developer"
   }
]

Single custom attribute

Get a single custom attribute on a resource.

Copy to clipboard
GET /users/:id/custom_attributes/:key
GET /groups/:id/custom_attributes/:key
GET /projects/:id/custom_attributes/:key
Attribute Type Required Description
id integer yes The ID of a resource
key string yes The key of the custom attribute
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location"

Example response:

Copy to clipboard
{
   "key": "location",
   "value": "Antarctica"
}

Set custom attribute

Set a custom attribute on a resource. The attribute is updated if it already exists, or newly created otherwise.

Copy to clipboard
PUT /users/:id/custom_attributes/:key
PUT /groups/:id/custom_attributes/:key
PUT /projects/:id/custom_attributes/:key
Attribute Type Required Description
id integer yes The ID of a resource
key string yes The key of the custom attribute
value string yes The value of the custom attribute
Copy to clipboard
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --data "value=Greenland" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location"

Example response:

Copy to clipboard
{
   "key": "location",
   "value": "Greenland"
}

Delete custom attribute

Delete a custom attribute on a resource.

Copy to clipboard
DELETE /users/:id/custom_attributes/:key
DELETE /groups/:id/custom_attributes/:key
DELETE /projects/:id/custom_attributes/:key
Attribute Type Required Description
id integer yes The ID of a resource
key string yes The key of the custom attribute
Copy to clipboard
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location"