Upload a file with an upload ticket

Receives the bytes of an OUT-OF-BAND upload authorized by agendas.uploads.createTicket, and returns the staging ref to attach on an event write (image: { ref } or a custom additionalFields field). This is the endpoint the ticket descriptor's uploadUrl points at.

Call it with a plain HTTPS POST from outside the typed API client, so the file never transits the client (or an LLM's token stream). Authorize with the ticket in the X-Upload-Ticket header (no API key or access token) and send the file as multipart/form-data field file. The target agenda is taken from the signed ticket.

The type is detected from the file content, or from the filename extension for signature-less formats such as CSV; a type outside the platform's allowed set (images, PDF and common office documents) answers 422 with the code file.invalidType. The file is capped at 20 MiB (422 with the code file.tooBig past it).

A request without a file answers 422 with the code required on file; a file sent in another part, or a second file, answers 422 with the code file.unexpected on that part. A multipart body that cannot be read (cut short, without a boundary, a text part over 1 MiB) answers 400.

A successful upload consumes the ticket. A consumed or expired ticket answers 401, and uploading again takes a new ticket. A request rejected before staging (400, 422) leaves the ticket usable until it expires.