Creating Reference Columns via API

Ask for Help
1

I’m building an integration to duplicate table structures between documents via the REST API, and I’ve run into a
roadblock regarding Reference columns and their visual rendering (displayCol).

The Goal:
I want to copy a Reference column from Document A to Document B using the API so that it actually shows the label (e.g.,
“Year”) instead of the raw numeric ID.

The Issue:

  1. In the original document, the reference column’s visibleCol points to the target table’s ID column, but its
    displayCol points to an auto-generated, hidden column (e.g., gristHelper_Display with ID 48).
  2. The standard /columns endpoint hides these gristHelper_ columns, so my script cannot clone them.
  3. Even when I extract the hidden columns using the internal _grist_Tables_column endpoint, the API rejects any POST or
    PATCH requests trying to recreate or update a column named gristHelper_Display in the destination document
    (returning a 404: Column not found or similar error).
  4. If I just point displayCol to 0 or to the same ID as visibleCol, Grist leaves the cell rendering the raw row ID (1,
    2, 3…) until a user manually clicks the column options in the UI and selects the display column again (which
    prompts Grist to generate the gristHelper_Display column automatically).

The Question:
What is the officially supported way to create a Reference column via API so that it automatically displays the correct
label (from the target table) without requiring manual UI intervention to trigger the gristHelper creation? Is there a
payload property I am missing, or an endpoint that handles this cleanly?

Thanks in advance!