gitlab-org--gitlab-foss/doc/api/custom_attributes.md

stage	group	info
none	unassigned	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers

Custom Attributes API

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.

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

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

Example response:

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

Single custom attribute

Get a single custom attribute on a resource.

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

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location"

Example response:

{
   "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.

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

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:

{
   "key": "location",
   "value": "Greenland"
}

Delete custom attribute

Delete a custom attribute on a resource.

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

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/custom_attributes/location"