Links an existing file to a business entity (e.g., an invoice, message, or meeting). The referenced file must already exist and must not be infected, failed, or deleted; linking is allowed while the file is still processing ('pending', 'scanning') as well as once ready ('scanned', 'uploaded', 'linked'). If the file is later found infected or fails processing, any relation created for it is retracted. Once a file has at least one active relation its status becomes 'linked', protecting it from cleanup.

The caller must have access to the related entity: a Staff token is checked directly against the entity. A Client token is checked by querying the client's own activity on that entity — the entity must appear in the client's activity feed (matched by message text for entity_type='message', or by activity type for every other entity type). Any error or timeout from that check is treated as no access (fails closed).

For Client tokens, the client_uid is derived from the token and any value supplied in the body is ignored. For Staff tokens, client_uid may be provided to associate the relation with a specific client; omitting it returns a 400.

Available for Staff and Client tokens.