Allow writing file-level alt text via the Files API / private-app tokens

HubSpot Ideas
1

Problem

The Files API lets you read a file’s alt text (exposed as extended_metadata.alt_text on GET /filemanager/api/v3/files/{id}), but there is no supported way to write it with a private-app token:

  • PATCH /files/v3/files/{id} with an alt field returns 200 but silently drops the value — the alt is unchanged on re-read.
  • PATCH /filemanager/api/v3/files/{id}/meta (the endpoint the File Manager UI uses to save alt) returns 401 for token auth; it appears to require a browser session (cookies + X-HubSpot-CSRF-hubspotapi).

So file-level alt can only be set by a human clicking through the UI.

Why it matters

Alt text is an accessibility and SEO requirement. Teams managing large asset libraries need to set/normalize alt text in bulk and keep it under governance. Today that’s impossible to automate via the official API — every file must be edited by hand in the UI, which doesn’t scale and can’t be put under review.

Request

Expose file-level alt text as a writable field for private-app tokens — either:

  • accept and persist alt (or extended_metadata.alt_text) on PATCH /files/v3/files/{id}, or
  • provide a documented, token-authenticated endpoint to set a file’s alt text.

The files scope already governs file writes (rename/move/access), so alt would fit naturally under it.