custom_attributes.md 2.74 KB
Newer Older
1 2 3
# Custom Attributes API

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

Custom attributes are currently available on users, groups, and projects,
which will be referred to as "resource" in this documentation.
7 8 9

## List custom attributes

10
Get all custom attributes on a resource.
11 12 13

```
GET /users/:id/custom_attributes
14
GET /groups/:id/custom_attributes
15
GET /projects/:id/custom_attributes
16 17 18 19
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
20
| `id` | integer | yes | The ID of a resource |
21 22

```bash
23
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/custom_attributes
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
```

Example response:

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

## Single custom attribute

43
Get a single custom attribute on a resource.
44 45 46

```
GET /users/:id/custom_attributes/:key
47
GET /groups/:id/custom_attributes/:key
48
GET /projects/:id/custom_attributes/:key
49 50 51 52
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
53
| `id` | integer | yes | The ID of a resource |
54 55 56
| `key` | string | yes | The key of the custom attribute |

```bash
57
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/custom_attributes/location
58 59 60 61 62 63 64 65 66 67 68 69 70
```

Example response:

```json
{
   "key": "location",
   "value": "Antarctica"
}
```

## Set custom attribute

71
Set a custom attribute on a resource. The attribute will be updated if it already exists,
72 73 74 75
or newly created otherwise.

```
PUT /users/:id/custom_attributes/:key
76
PUT /groups/:id/custom_attributes/:key
77
PUT /projects/:id/custom_attributes/:key
78 79 80 81
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
82
| `id` | integer | yes | The ID of a resource |
83 84 85 86
| `key` | string | yes | The key of the custom attribute |
| `value` | string | yes | The value of the custom attribute |

```bash
87
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "value=Greenland" https://gitlab.example.com/api/v4/users/42/custom_attributes/location
88 89 90 91 92 93 94 95 96 97 98 99 100
```

Example response:

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

## Delete custom attribute

101
Delete a custom attribute on a resource.
102 103 104

```
DELETE /users/:id/custom_attributes/:key
105
DELETE /groups/:id/custom_attributes/:key
106
DELETE /projects/:id/custom_attributes/:key
107 108 109 110
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
111
| `id` | integer | yes | The ID of a resource |
112 113 114
| `key` | string | yes | The key of the custom attribute |

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