Brand Templates

Update a brand template

Changes the settings of a brand template that already exists.

IT IS SHARED. Every report printed with the template and every client portal view wearing it changes with it, from the next time they are drawn. /v1/brand-templates/delete names them when it refuses to delete one.

THE UPDATE IS PARTIAL: the fields the body carries are written and every other column is left as it is, the logo and the cover image included. The answer carries before with the whole template in the same shape, so sending that block back undoes the call.

TWO PAIRS THE SETTINGS WINDOW OF THE APPLICATION KEEPS AND THIS ENDPOINT KEEPS WITH IT. include_logo true over a template that carries no logo is refused with 400 and details.reason logo_required; cover_style 'image' over one that carries no cover image is refused with details.reason cover_image_required.

SETTING include_logo FALSE REMOVES THE LOGO. The flag and the file are one thing: unticking the checkbox in the settings window of the application blanks the file with it, and this endpoint does the same, in the same write. Nothing keeps a copy, so switching the flag on again needs a new upload through /v1/brand-templates/set-logo; the answer says so with a LOGO_REMOVED warning, and a read afterwards answers logo null. The other way to remove it is /v1/brand-templates/set-logo with a null file, which is refused while the flag is on.

A WRITE OF SETTINGS NEVER WRITES THE BYTES OF AN IMAGE. It writes the columns that are settings and leaves the logo and the cover image where they are, so an upload running at the same time is never undone by it; the one thing that reaches the logo column is the removal above, and it only ever writes an absence.

The brand of the platform, under the empty key, answers 409 NOT_ALLOWED with details.reason system_defined.

if_version is not accepted.

Refusals: 400 for the framework and the body, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND when the template is not this account's, 409 NOT_ALLOWED.

A brand template written through this API is not visible to an application window that is already open: the page has to be reloaded before the same template is edited there.

Every write endpoint reads dry_run and idempotency_key; see the Write guarantees section of the introduction.

post/brand-templates/update

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/brand-templates/update
  • Auth: HTTP bearer

Request body

brand_template_keystring required

The brand template to write. From /v1/brand-templates/list. The empty key is the brand of the platform and is refused with 409 NOT_ALLOWED.

namestring nullable
internal_notesstring nullable

A note for the account's own staff. Left out or null, it is left as it is.

font_familystring nullable

The font of the PDF. Left out or null, it is left as it is.

margin_topinteger nullable

The top margin of the page, in points. Left out or null, it is left as it is.

margin_bottominteger nullable

The bottom margin of the page, in points. Left out or null, it is left as it is.

margin_leftinteger nullable

The left margin of the page, in points. Left out or null, it is left as it is.

margin_rightinteger nullable

The right margin of the page, in points. Left out or null, it is left as it is.

report_title_text_colorstring nullable

The colour of the title of the cover, as #RRGGBB. Left out or null, it is left as it is.

report_title_font_sizeinteger nullable

The size of the title of the cover. Left out or null, it is left as it is.

report_title_font_weight'normal' | 'bold' nullable

The weight of the title of the cover. Left out or null, it is left as it is.

report_subtitle_text_colorstring nullable

The colour of the subtitle of the cover, as #RRGGBB. Left out or null, it is left as it is.

report_subtitle_font_sizeinteger nullable

The size of the subtitle of the cover. Left out or null, it is left as it is.

report_subtitle_font_weight'normal' | 'bold' nullable

The weight of the subtitle of the cover. Left out or null, it is left as it is.

section_name_text_colorstring nullable

The colour of the name of a section, as #RRGGBB. Left out or null, it is left as it is.

section_name_font_sizeinteger nullable

The size of the name of a section. Left out or null, it is left as it is.

section_name_font_weight'normal' | 'bold' nullable

The weight of the name of a section. Left out or null, it is left as it is.

date_range_text_colorstring nullable

The colour of the period line of a section, as #RRGGBB. Left out or null, it is left as it is.

date_range_font_sizeinteger nullable

The size of the period line of a section. Left out or null, it is left as it is.

date_range_font_weight'normal' | 'bold' nullable

The weight of the period line of a section. Left out or null, it is left as it is.

component_name_text_colorstring nullable

The colour of the name of a widget, as #RRGGBB. Left out or null, it is left as it is.

component_name_font_sizeinteger nullable

The size of the name of a widget. Left out or null, it is left as it is.

component_name_font_weight'normal' | 'bold' nullable

The weight of the name of a widget. Left out or null, it is left as it is.

footer_text_colorstring nullable

The colour of the footer, as #RRGGBB. Left out or null, it is left as it is.

footer_font_sizeinteger nullable

The size of the footer. Left out or null, it is left as it is.

footer_font_weight'normal' | 'bold' nullable

The weight of the footer. Left out or null, it is left as it is.

include_logoboolean nullable

Whether the report prints the logo. It cannot be true on a template that carries none, and setting it FALSE REMOVES the file, which is what the settings window of the application does when the checkbox is unticked: nothing keeps a copy, so switching it on again needs a new upload through /v1/brand-templates/set-logo. The answer says so with a LOGO_REMOVED warning. Left out or null, it is left as it is.

include_section_lineboolean nullable

Whether a line is drawn under the name of a section. Left out or null, it is left as it is.

section_line_colorstring nullable

The colour of that line, as #RRGGBB. Left out or null, it is left as it is.

component_name_background_colorstring nullable

The background behind the name of a widget, as #RRGGBB. Left out or null, it is left as it is.

component_content_text_colorstring nullable

The colour of the content of a widget, as #RRGGBB. Left out or null, it is left as it is.

component_content_font_sizeinteger nullable

The size of the content of a widget. Left out or null, it is left as it is.

colorsstring[] nullable

The palette the charts are drawn with, in order, as #RRGGBB. Left out or null, it is left as it is.

footer_contentstring nullable

The text of the footer. Left out or null, it is left as it is.

include_footer_lineboolean nullable

Whether a line is drawn above the footer. Left out or null, it is left as it is.

footer_line_colorstring nullable

The colour of that line, as #RRGGBB. Left out or null, it is left as it is.

primary_colorstring nullable

The main colour of the brand, as #RRGGBB. Left out or null, it is left as it is.

cover_style'gradient' | 'plain' | 'aurora' | 'circles' | 'waves' | 'diagonal' | 'rings' | 'dots' | 'bubbles' | 'contours' | 'blocks' | 'image' nullable

The style the front cover is drawn with. A template that never picked one is read as plain, which is what it is drawn with. Left out or null, it is left as it is.

cover_tone'auto' | 'light' | 'dark' | 'custom' nullable

The tone of the text of the cover. auto takes it from the primary colour and is what a template that never picked one is read as. Left out or null, it is left as it is.

cover_text_colorstring nullable

The colour of the cover text when the tone is custom, as #RRGGBB. Left out or null, it is left as it is.

cover_invertedboolean nullable

Whether the cover is drawn on a coloured surface instead of white paper. Left out or null, it is left as it is.

prepared_bystring nullable

The line naming who prepared the report. Left out or null, it is left as it is.

prepared_forstring nullable

The line naming who it was prepared for. Left out or null, it is left as it is.

toc_style'cards' | 'rule' | 'band' | 'timeline' nullable

The style of the table of contents. A template that never picked one is read as timeline. Left out or null, it is left as it is.

portal_header_style'none' | 'letterhead' | 'card' | 'band' nullable

The header the client portal wears. none draws no header and is what a template that never picked one is read as. Left out or null, it is left as it is.

portal_header_logoboolean nullable

Whether that header carries the logo. Left out or null, it is left as it is.

web_font_familystring nullable

The font of the client portal and of a public link. app_default is the font of the application. Left out or null, it is left as it is.

is_systemboolean nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

logoobject nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

cover_imageobject nullable

Ignored on a write: part of what a read publishes and not part of what a write stores. It is accepted so the object /v1/brand-templates/get answers can be sent straight back, and it comes back as a READ_ONLY_FIELD_IGNORED warning.

dry_runboolean

Validate everything and write nothing.

idempotency_keystring

Replays the answer of an identical call for 24 hours.

Response

The call succeeded. This endpoint reports its errors with a real HTTP status, so a 200 always carries status=ok.

status'ok' required

Changes

No recorded changes to this operation across all 1 revision of this API.