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 and Update accept a small subset of branding keys; this endpoint exposes the full set.

Action	Endpoint
Get branding	GET /api/projects/{projectId}/status-pages/{statusPageId}/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.

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

cURL

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.

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

cURL

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