Add a picture to a section

Writes one picture -- a logo, a screenshot, a diagram -- as one more widget of a section.

IT IS THE ONE WIDGET THAT IS A FILE AND NOT A DEFINITION, which is why it has a route of its own: there is nothing about a picture that the widget DSL could describe. /v1/reports/get answers type: image and editable: false for it, with the size of the picture and the weight of its file under image, and never the bytes.

image_base64 carries the file itself, base64 encoded and with no data URI prefix, up to 716800 bytes DECODED. That ceiling is lower than the 1 MB the application accepts from an upload because these bytes travel encoded inside the request body, which is capped at 1 MB: a bigger one is answered 413 before this endpoint sees it.

THE BYTES DECIDE WHAT THE FILE IS. The size, the first bytes (JPEG, PNG or GIF) and finally whether the picture really decodes are all checked, in that order, whatever the filename says; anything else is refused by name. A file that is refused is 400 INVALID_VALUE with the rule that stopped it in details.reason, one of: too_large (over 716800 decoded bytes), too_many_pixels (the header announces more than 25000000 pixels, which is a picture nothing draws and a decode nothing should pay for), format_not_supported (the first bytes are not a JPEG, a PNG or a GIF, whatever the file is called) and not_an_image (the bytes announce a format and do not decode as one). The width and the height are read off the picture and are not chosen by the caller, exactly as in the application, and they are read from the HEADER first: a file of a few hundred KB can announce twenty thousand pixels a side and decode into hundreds of megabytes, so the ceiling of pixels is applied before anything is decoded -- on a dry run too, which validates everything.

Without a placement the widget goes to the first row that takes it. An image is not a KPI, so it counts as one of the elements a row holds; a row holding a page break takes nobody else. A report built on a template is refused with 400 APPEND_NOT_ALLOWED, reason template_based.

Refusals: 400 for the framework and the body, 400 INVALID_VALUE, 400 APPEND_NOT_ALLOWED, 403 WRITE_ACCESS_DISABLED, 404 NOT_FOUND, 409 VERSION_MISMATCH, 409 SECTION_BUSY, 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.