Skip to main content

Change theme

PATCH https://api.rollstack.com/public/v1/reports/{id}/theme

Changes a slide deck's theme: its colours, its heading font and its body font. This is how a deck takes a brand's colours, such as the ones the user names or the ones of a presentation they gave you: read the colours yourself and send each in the slot whose job it does. Every slide follows wherever it uses the theme's colours, and so do the template's layouts and the slides you write next, which keep using the theme variables that getReportDesign lists. Call it before you write slides, then call getReportDesign again for the colours as they are now. A slot sent with a colour another slot already has is saved one step of blue away from it (#2D6A4F and #2D6A50), which looks the same: saved slides tell theme colours apart by their value, so the answer can differ from what you sent by that step. A change that would leave text unreadable on its background changes nothing and answers the pair to fix, and so does a font the editor does not have. A new font sets text wider or narrower than the old one: on a deck that already has slides, look at each with getReportSlideImages afterwards and save again the ones whose text no longer fits. It changes colours and fonts only: for a presentation's layouts and logo, the user imports it as a template in Rollstack, which answers in listTemplates. Only the report's editors may. Answers the theme after the change and the version saved before it.

Requires the slide_decks:write scope.

Operation ID: updateReportTheme.

Path parameters

  • id (string, required): The report to act on, by its id from listReports or createReport. Only reports whose type is SlideDeck work here: another type, such as a Google Slides presentation, returns 400. You can also copy it from the report's link in Rollstack: it's the part right after /slides/.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • colors (object): The theme colours to change, each as #RRGGBB. The ones left out stay as they are. Each has a job on the slides, so put a brand's colours where they belong: its dark text colour in dark1, its background in light1, its main brand colour in accent1.
    • dark1 (string): Main text: titles and body text on the slide background.
    • dark2 (string): Secondary text: captions, sources and muted labels, quieter than dark1 but readable.
    • light1 (string): The slide background.
    • light2 (string): The second surface: cards, panels and table header rows. Close to light1 but visibly different from it.
    • accent1 (string): The main highlight: key numbers, accent bars and rules, the first chart series.
    • accent2 (string): The second chart series and highlight.
    • accent3 (string): The third chart series and highlight.
    • accent4 (string): The fourth chart series and highlight.
    • accent5 (string): The fifth chart series and highlight.
    • accent6 (string): The sixth chart series and highlight.
    • hyperlink (string): Link text, readable on light1.
    • followedHyperlink (string): Visited link text, readable on light1.
  • headingFont (string): The font family for titles and headings, by its published name, such as Inter. A font the editor does not have is refused.
  • bodyFont (string): The font family for all other text, by its published name.

Response 200

Success

application/json

  • When changed is true
    • changed (true, required)
    • versionBeforeId (string, required): The version saved just before the change: restore it with restoreReportVersion to take the change back.
    • colors (object, required): The report's theme colours after the change, by slot, as getReportDesign lists them in theme.
    • headingFont (string, required): The font of titles and headings after the change.
    • bodyFont (string, required): The font of all other text after the change.
  • When changed is false
    • changed (false, required)
    • refused (string, required): invalid: fix what reason names and send the change again. needs-agent: only Rollstack's agent can make this change, so ask the user whether to hand it over with sendReportMessage. One of invalid, needs-agent.
    • reason (string, required): Why nothing changed: the pairs of colours the change would leave unreadable, a font the editor lacks, or a background picture that could not be read.