2020-10-26 21:08:22 +00:00
---
2020-11-17 15:09:28 +00:00
stage: Manage
group: Access
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-26 21:08:22 +00:00
---
2020-01-09 06:07:57 +00:00
# Appearance API **(CORE ONLY)**
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16647) in GitLab 12.7.
2020-01-09 06:07:57 +00:00
Appearance API allows you to maintain GitLab's appearance as if using the GitLab UI at
`/admin/appearance` . The API requires administrator privileges.
## Get current appearance configuration
List the current appearance configuration of the GitLab instance.
2020-02-27 09:09:01 +00:00
```plaintext
2020-01-09 06:07:57 +00:00
GET /application/appearance
```
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/application/appearance"
2020-01-09 06:07:57 +00:00
```
Example response:
```json
{
"title": "GitLab Test Instance",
"description": "gitlab-test.example.com",
"logo": "/uploads/-/system/appearance/logo/1/logo.png",
"header_logo": "/uploads/-/system/appearance/header_logo/1/header.png",
"favicon": "/uploads/-/system/appearance/favicon/1/favicon.png",
"new_project_guidelines": "Please read the FAQs for help.",
2020-04-28 15:09:29 +00:00
"profile_image_guidelines": "Custom profile image guidelines",
2020-01-09 06:07:57 +00:00
"header_message": "",
"footer_message": "",
"message_background_color": "#e75e40",
"message_font_color": "#ffffff",
"email_header_and_footer_enabled": false
}
```
## Change appearance configuration
Use an API call to modify GitLab instance appearance configuration.
2020-02-27 09:09:01 +00:00
```plaintext
2020-01-09 06:07:57 +00:00
PUT /application/appearance
```
| Attribute | Type | Required | Description |
| --------------------------------- | ------- | -------- | ----------- |
| `title` | string | no | Instance title on the sign in / sign up page
| `description` | string | no | Markdown text shown on the sign in / sign up page
2020-11-19 18:09:13 +00:00
| `logo` | mixed | no | Instance image used on the sign in / sign up page. See [Change logo ](#change-logo )
2020-01-09 06:07:57 +00:00
| `header_logo` | mixed | no | Instance image used for the main navigation bar
2020-06-02 18:08:32 +00:00
| `favicon` | mixed | no | Instance favicon in `.ico` or `.png` format
2020-01-09 06:07:57 +00:00
| `new_project_guidelines` | string | no | Markdown text shown on the new project page
2020-04-28 15:09:29 +00:00
| `profile_image_guidelines` | string | no | Markdown text shown on the profile page below Public Avatar
2020-01-09 06:07:57 +00:00
| `header_message` | string | no | Message within the system header bar
| `footer_message` | string | no | Message within the system footer bar
| `message_background_color` | string | no | Background color for the system header / footer bar
| `message_font_color` | string | no | Font color for the system header / footer bar
| `email_header_and_footer_enabled` | boolean | no | Add header and footer to all outgoing emails if enabled
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/application/appearance?email_header_and_footer_enabled=true& header_message=test"
2020-01-09 06:07:57 +00:00
```
Example response:
```json
{
"title": "GitLab Test Instance",
"description": "gitlab-test.example.com",
"logo": "/uploads/-/system/appearance/logo/1/logo.png",
"header_logo": "/uploads/-/system/appearance/header_logo/1/header.png",
"favicon": "/uploads/-/system/appearance/favicon/1/favicon.png",
"new_project_guidelines": "Please read the FAQs for help.",
2020-04-28 15:09:29 +00:00
"profile_image_guidelines": "Custom profile image guidelines",
2020-01-09 06:07:57 +00:00
"header_message": "test",
"footer_message": "",
"message_background_color": "#e75e40",
"message_font_color": "#ffffff",
"email_header_and_footer_enabled": true
}
```
2020-11-19 18:09:13 +00:00
## Change logo
Upload a logo to your GitLab instance.
To upload an avatar from your file system, use the `--form` argument. This causes
cURL to post data using the header `Content-Type: multipart/form-data` . The
2020-12-03 21:09:35 +00:00
`file=` parameter must point to an image file on your file system and be
2020-11-19 18:09:13 +00:00
preceded by `@` .
```plaintext
PUT /application/appearance
```
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | -------------- |
| `logo` | string | Yes | File to upload |
Example request:
```shell
curl --location --request PUT "https://gitlab.example.com/api/v4/application/appearance?data=image/png" \
--header "Content-Type: multipart/form-data" \
--header "PRIVATE-TOKEN: < your_access_token > " \
--form "logo=@/path/to/logo.png"
```
Returned object:
```json
{
"logo":"/uploads/-/system/appearance/logo/1/logo.png"
```