branding

14 endpoints.

GET/api/branding Bearer token

Read the deployment branding

The long-form and short names, the logos and favicons, and the support address this deployment shows in place of the Botree defaults. Null fields mean the default — or, for a dark-mode logo or a favicon, the image it falls back to — is in use.

Responses

Status	Description	Body
200	The current branding.	DeploymentBranding
401	The access token is missing or invalid.	ErrorResponse
500	The deployment branding could not be read.	ErrorResponse

PATCH/api/branding Bearer token

Set the deployment's names and support address

Sets the long-form name shown in the footer, page titles, notification emails and the dashboard top bar on wide screens, and the short name shown as the dashboard wordmark and the top bar title on narrow screens. Either falls back to the other when only one is set; send null or an empty string to clear one, and omit a field to leave it unchanged. The footer keeps a "Powered by Botree LRS" credit while a custom name or logo is set. The support address is the one the public /support pages tell people to write to for help, support@botreeinc.com until one is set. Requires a superuser's access token.

Request body

application/jsonrequiredUpdateDeploymentBrandingRequest

Field	Type	Required	Description
display_name	string \| null	no	The long-form name to show; send null or an empty string to restore the default. Omit to leave it unchanged. at most 100 characters
short_name	string \| null	no	The short name for the dashboard wordmark and the top bar on narrow screens; send null or an empty string to fall back to the long-form name. Omit to leave it unchanged. at most 40 characters
support_email	string \| null	no	The address the public /support pages tell people to write to for help; stored lowercased. Send null or an empty string to restore the default, support@botreeinc.com. Omit to leave it unchanged. at most 254 characters

Field

Type

Required

Description

display_name

string | null

The long-form name to show; send null or an empty string to restore the default. Omit to leave it unchanged.

at most 100 characters

short_name

string | null

The short name for the dashboard wordmark and the top bar on narrow screens; send null or an empty string to fall back to the long-form name. Omit to leave it unchanged.

at most 40 characters

support_email

string | null

The address the public /support pages tell people to write to for help; stored lowercased. Send null or an empty string to restore the default, support@botreeinc.com. Omit to leave it unchanged.

at most 254 characters

Responses

Status	Description	Body
200	The updated branding.	DeploymentBranding
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The deployment branding could not be written to.	ErrorResponse

GET/api/branding/logo Public

Serve the deployment's logo

The uploaded logo's bytes, with its content type. Public — it is shown in the header, footer and home page — in dark mode too, unless a dark-mode logo is set — and in the browser tab while no favicon is, signed in or not — and 404 while none is uploaded, when the pages show the Botree artwork instead. The response is cacheable for a year: the pages append a version query that changes with every branding write, so a replaced image is fetched under a new URL. A `size` query fits a PNG, JPEG or WebP image inside a square of that many pixels (snapped up to the nearest of 16, 32, 48, 64, 96, 128, 256, 384, 512 or 1024); an SVG, GIF or ICO is served as uploaded whatever the size.

Parameters

Name	In	Type	Required	Description
v	query	string	no	Cache-busting version, as the branding endpoints report it. Ignored here.
size	query	integer	no	The rendition to serve, in pixels: the image is fitted inside a square of this size (snapped up to the nearest bucket, and never enlarged). Omit for the upload at its full resolution.

Responses

Status	Description	Body
200	The image, served with the upload's content type.	—
400	The size query is not a positive integer.	ErrorResponse
404	No logo has been uploaded.	ErrorResponse
500	The deployment branding could not be read.	ErrorResponse
502	The image could not be read from storage.	ErrorResponse

POST/api/branding/logo Bearer token

Upload the deployment's logo

Replaces the image shown in the header, footer and home page — in dark mode too, unless a dark-mode logo is set — and in the browser tab while no favicon is with the one in the file part: PNG, JPEG, WebP, GIF or SVG, at most 2 MB. Square artwork fits best. Requires a superuser's access token.

Request body

multipart/form-datarequiredDeploymentBrandingImageForm

Field	Type	Required	Description
file	string (binary)	yes	The image, as a file part: PNG, JPEG, WebP, GIF or SVG — or, for a favicon, ICO — at most 2 MB. Square artwork fits best.

Responses

Status	Description	Body
200	The updated branding, its logo URL pointing at the new image.	DeploymentBranding
400	The file part is missing, not an accepted image type, or too large.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The image could not be stored, or the write failed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

DELETE/api/branding/logo Bearer token

Remove the deployment's logo

Shows the Botree artwork in the header, footer and home page — in dark mode too, unless a dark-mode logo is set — and in the browser tab while no favicon is again. Requires a superuser's access token.

Responses

Status	Description	Body
200	The updated branding, with no logo.	DeploymentBranding
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The deployment branding could not be written to.	ErrorResponse

GET/api/branding/logo/dark Public

Serve the deployment's dark-mode logo

The uploaded dark-mode logo's bytes, with its content type. Public — it is shown in the header, footer and home page while the app is in dark mode, signed in or not — and 404 while none is uploaded, when the pages show the light-mode logo instead. The response is cacheable for a year: the pages append a version query that changes with every branding write, so a replaced image is fetched under a new URL. A `size` query fits a PNG, JPEG or WebP image inside a square of that many pixels (snapped up to the nearest of 16, 32, 48, 64, 96, 128, 256, 384, 512 or 1024); an SVG, GIF or ICO is served as uploaded whatever the size.

Parameters

Name	In	Type	Required	Description
v	query	string	no	Cache-busting version, as the branding endpoints report it. Ignored here.
size	query	integer	no	The rendition to serve, in pixels: the image is fitted inside a square of this size (snapped up to the nearest bucket, and never enlarged). Omit for the upload at its full resolution.

Responses

Status	Description	Body
200	The image, served with the upload's content type.	—
400	The size query is not a positive integer.	ErrorResponse
404	No dark-mode logo has been uploaded.	ErrorResponse
500	The deployment branding could not be read.	ErrorResponse
502	The image could not be read from storage.	ErrorResponse

POST/api/branding/logo/dark Bearer token

Upload the deployment's dark-mode logo

Replaces the image shown in the header, footer and home page while the app is in dark mode with the one in the file part: PNG, JPEG, WebP, GIF or SVG, at most 2 MB. Square artwork fits best. Requires a superuser's access token.

Request body

multipart/form-datarequiredDeploymentBrandingImageForm

Field	Type	Required	Description
file	string (binary)	yes	The image, as a file part: PNG, JPEG, WebP, GIF or SVG — or, for a favicon, ICO — at most 2 MB. Square artwork fits best.

Responses

Status	Description	Body
200	The updated branding, its dark-mode logo URL pointing at the new image.	DeploymentBranding
400	The file part is missing, not an accepted image type, or too large.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The image could not be stored, or the write failed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

DELETE/api/branding/logo/dark Bearer token

Remove the deployment's dark-mode logo

Shows the light-mode logo in the header, footer and home page while the app is in dark mode again. Requires a superuser's access token.

Responses

Status	Description	Body
200	The updated branding, with no dark-mode logo.	DeploymentBranding
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The deployment branding could not be written to.	ErrorResponse

GET/api/branding/favicon Public

Serve the deployment's favicon

The uploaded favicon's bytes, with its content type. Public — it is shown in the browser tab, signed in or not — and 404 while none is uploaded, when the pages show the logo instead. The response is cacheable for a year: the pages append a version query that changes with every branding write, so a replaced image is fetched under a new URL. A `size` query fits a PNG, JPEG or WebP image inside a square of that many pixels (snapped up to the nearest of 16, 32, 48, 64, 96, 128, 256, 384, 512 or 1024); an SVG, GIF or ICO is served as uploaded whatever the size.

Parameters

Name	In	Type	Required	Description
v	query	string	no	Cache-busting version, as the branding endpoints report it. Ignored here.
size	query	integer	no	The rendition to serve, in pixels: the image is fitted inside a square of this size (snapped up to the nearest bucket, and never enlarged). Omit for the upload at its full resolution.

Responses

Status	Description	Body
200	The image, served with the upload's content type.	—
400	The size query is not a positive integer.	ErrorResponse
404	No favicon has been uploaded.	ErrorResponse
500	The deployment branding could not be read.	ErrorResponse
502	The image could not be read from storage.	ErrorResponse

POST/api/branding/favicon Bearer token

Upload the deployment's favicon

Replaces the image shown in the browser tab with the one in the file part: PNG, JPEG, WebP, GIF, SVG or ICO, at most 2 MB. Square artwork fits best. Requires a superuser's access token.

Request body

multipart/form-datarequiredDeploymentBrandingImageForm

Field	Type	Required	Description
file	string (binary)	yes	The image, as a file part: PNG, JPEG, WebP, GIF or SVG — or, for a favicon, ICO — at most 2 MB. Square artwork fits best.

Responses

Status	Description	Body
200	The updated branding, its favicon URL pointing at the new image.	DeploymentBranding
400	The file part is missing, not an accepted image type, or too large.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The image could not be stored, or the write failed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

DELETE/api/branding/favicon Bearer token

Remove the deployment's favicon

Shows the logo in the browser tab again. Requires a superuser's access token.

Responses

Status	Description	Body
200	The updated branding, with no favicon.	DeploymentBranding
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The deployment branding could not be written to.	ErrorResponse

GET/api/branding/favicon/dark Public

Serve the deployment's dark-mode favicon

The uploaded dark-mode favicon's bytes, with its content type. Public — it is shown in the browser tab while the browser is in dark mode, signed in or not — and 404 while none is uploaded, when the pages show the favicon (or, with none set, the dark-mode logo) instead. The response is cacheable for a year: the pages append a version query that changes with every branding write, so a replaced image is fetched under a new URL. A `size` query fits a PNG, JPEG or WebP image inside a square of that many pixels (snapped up to the nearest of 16, 32, 48, 64, 96, 128, 256, 384, 512 or 1024); an SVG, GIF or ICO is served as uploaded whatever the size.

Parameters

Name	In	Type	Required	Description
v	query	string	no	Cache-busting version, as the branding endpoints report it. Ignored here.
size	query	integer	no	The rendition to serve, in pixels: the image is fitted inside a square of this size (snapped up to the nearest bucket, and never enlarged). Omit for the upload at its full resolution.

Responses

Status	Description	Body
200	The image, served with the upload's content type.	—
400	The size query is not a positive integer.	ErrorResponse
404	No dark-mode favicon has been uploaded.	ErrorResponse
500	The deployment branding could not be read.	ErrorResponse
502	The image could not be read from storage.	ErrorResponse

POST/api/branding/favicon/dark Bearer token

Upload the deployment's dark-mode favicon

Replaces the image shown in the browser tab while the browser is in dark mode with the one in the file part: PNG, JPEG, WebP, GIF, SVG or ICO, at most 2 MB. Square artwork fits best. Requires a superuser's access token.

Request body

multipart/form-datarequiredDeploymentBrandingImageForm

Field	Type	Required	Description
file	string (binary)	yes	The image, as a file part: PNG, JPEG, WebP, GIF or SVG — or, for a favicon, ICO — at most 2 MB. Square artwork fits best.

Responses

Status	Description	Body
200	The updated branding, its dark-mode favicon URL pointing at the new image.	DeploymentBranding
400	The file part is missing, not an accepted image type, or too large.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The image could not be stored, or the write failed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

DELETE/api/branding/favicon/dark Bearer token

Remove the deployment's dark-mode favicon

Shows the favicon (or, with none set, the dark-mode logo) in the browser tab while the browser is in dark mode again. Requires a superuser's access token.

Responses

Status	Description	Body
200	The updated branding, with no dark-mode favicon.	DeploymentBranding
401	The access token is missing or invalid.	ErrorResponse
403	The access token's subject is not a superuser.	ErrorResponse
500	The deployment branding could not be written to.	ErrorResponse