> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status Page Branding

> Read and update the colours, images, fonts and company details of a status page

## Overview

Branding controls how a status page looks. [Create](/api-reference/status-pages/create) and [Update](/api-reference/status-pages/update) accept a small subset of branding keys; this endpoint exposes the full set.

| Action | Endpoint |
| - | - |
| [Get branding](#get-branding) | `GET /api/projects/{projectId}/status-pages/{statusPageId}/branding` |
| [Update branding](#update-branding) | `PATCH /api/projects/{projectId}/status-pages/{statusPageId}/branding` (`POST` behaves the same) |

## Authentication

| Header | Required | Description |
| - | - | - |
| `X-API-Key` | Yes | Your API key (`Authorization: Bearer {jwt}` also works). Updating needs the `read_write` scope. |
| `Content-Type` | Yes (update) | `application/json` |

**Required access:** project viewer or higher to read; project admin to update. No `X-Project-ID` header is needed.

## Path parameters

| Parameter | Type | Description |
| - | - | - |
| `projectId` | UUID | The project |
| `statusPageId` | UUID | The status page |

## Branding fields

All keys are camelCase. Legacy snake\_case spellings (`logo_url`, `primary_color`, `custom_css`, `theme`) are accepted on input. Colours are hex `#RRGGBB`. Image and link URLs must use HTTPS. Any field that allows `null` can be cleared by sending `null`.

| Field | Type | Description |
| - | - | - |
| `primaryColor`, `accentColor` | string | Brand colours |
| `backgroundColor`, `surfaceColor` | string | Page and card backgrounds |
| `textColor`, `textMutedColor` | string | Text colours |
| `headerBackgroundColor`, `headerTextColor` | string | Header colours |
| `successColor`, `warningColor`, `errorColor` | string | Status colours |
| `logoUrl`, `faviconUrl`, `headerImageUrl`, `footerImageUrl` | string \| null | HTTPS image URLs |
| `logoWidth` | integer | 50-500 pixels |
| `logoHeight` | integer | 20-200 pixels |
| `fontFamily` | string | Up to 100 characters |
| `fontUrl` | string \| null | HTTPS font stylesheet URL |
| `companyName` | string \| null | Up to 255 characters |
| `footerText` | string \| null | Up to 1000 characters |
| `supportEmail` | string \| null | Valid email address |
| `supportUrl` | string \| null | HTTPS URL |
| `hideUptimeioBranding` | boolean | Hide the UptimeIO badge. Setting it to `true` requires the Scale plan; `false` is always allowed. |
| `customCss` | string \| null | Up to 10,000 characters; sanitised before it is stored |
| `defaultTheme` | string | `light`, `dark` or `system` |

## Get branding

Returns the stored branding. If none is stored, `branding` is an empty object and `message` is `Using default branding`.

```json theme={null}
{
  "success": true,
  "data": {
    "branding": {
      "primaryColor": "#0066CC",
      "defaultTheme": "light",
      "logoUrl": "https://example.com/logo.png"
    },
    "message": "Branding retrieved successfully"
  }
}
```

```bash cURL theme={null}
curl https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/branding \
  -H "X-API-Key: YOUR_API_KEY"
```

## Update branding

Send only the fields to change; they are merged into the existing branding. The response returns the full merged branding.

```json theme={null}
{
  "success": true,
  "data": {
    "branding": {
      "primaryColor": "#0066CC",
      "companyName": "Acme Inc.",
      "defaultTheme": "dark"
    },
    "message": "Branding updated successfully"
  }
}
```

```bash cURL theme={null}
curl -X PATCH https://api.uptimeio.com/api/projects/YOUR_PROJECT_ID/status-pages/YOUR_STATUS_PAGE_ID/branding \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "primaryColor": "#0066CC", "companyName": "Acme Inc.", "defaultTheme": "dark" }'
```

## Errors

| Status | Code | Cause |
| - | - | - |
| 400 | `VALIDATION_ERROR` | Invalid value, for example a colour that is not `#RRGGBB` or an image URL that is not HTTPS |
| 401 | `AUTHENTICATION_REQUIRED` | Missing or invalid credentials |
| 403 | `INSUFFICIENT_PERMISSIONS` | Updating without project admin access |
| 403 | `ACCESS_DENIED` | No access to the project, or the page belongs to another project |
| 403 | `API_KEY_ORGANIZATION_MISMATCH` | The API key belongs to a different organization than the project |
| 403 | `READ_ONLY_API_KEY` | The API key has the `read` scope and the request writes data |
| 403 | `FEATURE_NOT_AVAILABLE` | `hideUptimeioBranding` set to `true` on a Free or Pro plan: message `Hiding UptimeIO branding is not available on Free or Pro plans. Upgrade to Scale.` |
| 404 | `RESOURCE_NOT_FOUND` | The status page does not exist |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.