Upload or remove the front cover PDF of a report

Uploads the PDF the front cover of a report prints, or removes the one it carries. It is the one thing of the settings window of a report that is a FILE and not a setting: everything else of that window -- the cover type, its texts, its date line, the brand, the localization -- is written by /v1/reports/update.

THE FILE AND THE COVER TYPE ARE WRITTEN TOGETHER, and this call resolves the type itself. Uploading a file moves the type to the one that prints it (none to pdf, report to pdf_and_report) and file: null moves it back to the one that prints none. The answer says so with a COVER_TYPE_SET warning whenever the type changed, and updated_fields names what really changed: front_cover.file and, when the type moved, front_cover.type. A report never holds a file under a type that does not print it -- the settings window of the application throws such a file away the next time it saves the report -- nor a type that prints one with no file, which that window refuses to save.

THE TWO LEGACY COVER TYPES MOVE NOWHERE. pdf_and_custom already prints an uploaded PDF and the application shows the upload field for it, so a REPLACEMENT file is written and the type stays pdf_and_custom: there is no COVER_TYPE_SET warning, updated_fields carries front_cover.file alone and the cover texts of the report are left as they are. What is refused, with 400 INVALID_VALUE and details.reason legacy_cover_type, is what would move the cover from one half of that legacy pair to the other: a file sent to a report whose cover is custom -- where the application does not even show the upload -- and file: null on a pdf_and_custom one, whose destination would be custom. Neither move is one the application or /v1/reports/update makes; change the cover type in the application instead.

THE PREVIOUS FILE IS NOT KEPT. No backup is taken of it, so putting back a file this call replaced or removed means uploading it again; before names the file that went and the type the report had. Nothing is dropped from the cache: a front cover is drawn when the PDF is built and is not a widget anybody executed.

A report built on a template is accepted: the front cover it prints is its own row and not its template's.

Refusals: 400 for the framework and the body, 400 INVALID_VALUE, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 REPORT_IN_TRASH and 413 PAYLOAD_TOO_LARGE.

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

A file that is refused is 400 INVALID_VALUE with the rule that stopped it in details.reason, one of: too_large (over the ceiling of the account, 262144 decoded bytes, 524288 for the few accounts that were given the larger one; the message names the one that was applied) and not_a_pdf (the first five bytes of the file are not %PDF-, whatever the file is called). THIS IS STRICTER THAN THE APPLICATION, whose upload looks at the extension of the file name and nothing else, and stricter than the reader that draws the cover: the header is asked for at the start of the file, so a PDF preceded by a byte order mark or by padding is refused here although the product would draw it. NOTHING OPENS THE DOCUMENT: a file that is a PDF only in its first bytes is accepted, stored, and fails later, when the report is built.