> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/data-catalog-data-lineage-and-grants-apis/xlsx.md).

# XLSX

## Download data structures as XLSX

> Exports data structures and their associated notes as an Excel (XLSX) workbook. This is the same format used by the upload endpoint, so a downloaded file can be edited and re‑uploaded.\
> \
> \*\*Permissions:\*\* Uses the active search permission from the request context, which depends on the request's \`Referer\` header:\
> \- \*\*'Link structures'\*\* when the referer points to a \`/concepts/\`, \`/ingests/\`, or \`/rules/\` page.\
> \- \*\*'View structures'\*\* in all other cases, including when no referer is sent.\
> The endpoint does not override the permission based on request body parameters, so the exported content is filtered exactly by the caller's effective search permission.\
> \
> \*\*Request body:\*\*\
> \- Search filters (\`query\`, \`filters\`, \`must\`, \`must\_not\`, \`with\`, \`without\`, \`sort\`, \`scroll\`, \`scroll\_id\`, \`data\_structure\_id\`, \`include\_children\`) – Same parameters as the structure search endpoint.\
> \- \`download\_type\` (optional, string) – Currently only \`"editable"\` is supported; produces the editable worksheet format.\
> \- \`note\_type\` (optional, string) – \`"published"\` (default) or \`"non\_published"\`. Determines which note content is exported. By default only published notes are included.\
> \- \`lang\` (optional, string) – Language for headers and content. Defaults to the server‑configured application language; the API does not read the browser language.\
> \- \`header\_labels\` (optional, object) – Custom column labels keyed by the original field name.\
> \- \`structure\_url\_schema\` (optional, string) – URL template used to populate the \`link\_to\_structure\` column.\
> \- \`page\`, \`size\` – Accepted but ignored; the export always contains all matching records.\
> \
> \*\*Workbook structure:\*\*\
> \- \*\*Sheets:\*\* one sheet per structure type. The sheet name is the structure type.\
> \- \*\*Common columns:\*\* \`external\_id\`, \`name\`, \`tech\_name\`, \`alias\_name\`, \`link\_to\_structure\`, \`domain\`, \`type\`, \`system\`, \`path\`.\
>   \- \`name\` – If the structure has an alias, the alias is shown; otherwise the technical name.\
>   \- \`tech\_name\` / \`alias\_name\` – Technical name and alias respectively. \`alias\_name\` may be empty when the structure has no alias. The alias is also included as a template field.\
>   \- \`link\_to\_structure\` – Link to the structure in the catalog for easy navigation.\
> \- \*\*Template fields:\*\* all fields of the structure's template. They are rendered as editable cells; required fields are not visually indicated.\
> \
> \*\*Field formats (relevant when re‑uploading the workbook):\*\*\
> \- \*\*Number\*\* – Excel cell format Number or General.\
> \- \*\*Date\*\* – Excel cell format Date, or Text whose value matches one of: \`yyyy-mm-dd\`, \`yyyy/mm/dd\`, \`dd-mm-yyyy\`, \`dd/mm/yyyy\`.\
> \- \*\*DateTime\*\* – Excel cell format Date, or Text whose value matches one of: \`yyyy-mm-dd hh:mm:ss\`, \`yyyy/mm/dd hh:mm:ss\`, \`dd-mm-yyyy hh:mm:ss\`, \`dd/mm/yyyy hh:mm:ss\`.\
> \- \*\*Link\*\* – \`\[Link text] (<https://example.com/)\\`.\\>
> \- \*\*User or Group\*\* – \`user:Full Name\` or \`group:Group Name\` / \`group:Group Alias\`. Example: \`user:Antonio García\`, \`group:Data Team\`.\
> \- \*\*User\*\* – The user's full name without the \`user:\` prefix.\
> \- \*\*Group\*\* – Group name or alias without the \`group:\` prefix.\
> \- \*\*Table / Dynamic Table\*\* – Column headers separated by semicolons (\`;\`), with a line break inside the cell separating headers from data rows.\
> \- \*\*Multiple Values\*\* – Values separated by pipe (\`|\`). Example: \`user1|user2|user3\`.\
> \- \*\*Rich Text\*\* – Downloaded and uploaded without formatting; remove the column unless uploading plain text content.\
> \- \*\*Dropdown / Radio / Checkbox\*\* – Values must match the template definition exactly (case‑sensitive).\
> \
> Language falls back to the configured default if the requested language is not configured or a translation is missing.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/data_structures/xlsx/download":{"post":{"description":"Exports data structures and their associated notes as an Excel (XLSX) workbook. This is the same format used by the upload endpoint, so a downloaded file can be edited and re‑uploaded.\n\n**Permissions:** Uses the active search permission from the request context, which depends on the request's `Referer` header:\n- **'Link structures'** when the referer points to a `/concepts/`, `/ingests/`, or `/rules/` page.\n- **'View structures'** in all other cases, including when no referer is sent.\nThe endpoint does not override the permission based on request body parameters, so the exported content is filtered exactly by the caller's effective search permission.\n\n**Request body:**\n- Search filters (`query`, `filters`, `must`, `must_not`, `with`, `without`, `sort`, `scroll`, `scroll_id`, `data_structure_id`, `include_children`) – Same parameters as the structure search endpoint.\n- `download_type` (optional, string) – Currently only `\"editable\"` is supported; produces the editable worksheet format.\n- `note_type` (optional, string) – `\"published\"` (default) or `\"non_published\"`. Determines which note content is exported. By default only published notes are included.\n- `lang` (optional, string) – Language for headers and content. Defaults to the server‑configured application language; the API does not read the browser language.\n- `header_labels` (optional, object) – Custom column labels keyed by the original field name.\n- `structure_url_schema` (optional, string) – URL template used to populate the `link_to_structure` column.\n- `page`, `size` – Accepted but ignored; the export always contains all matching records.\n\n**Workbook structure:**\n- **Sheets:** one sheet per structure type. The sheet name is the structure type.\n- **Common columns:** `external_id`, `name`, `tech_name`, `alias_name`, `link_to_structure`, `domain`, `type`, `system`, `path`.\n  - `name` – If the structure has an alias, the alias is shown; otherwise the technical name.\n  - `tech_name` / `alias_name` – Technical name and alias respectively. `alias_name` may be empty when the structure has no alias. The alias is also included as a template field.\n  - `link_to_structure` – Link to the structure in the catalog for easy navigation.\n- **Template fields:** all fields of the structure's template. They are rendered as editable cells; required fields are not visually indicated.\n\n**Field formats (relevant when re‑uploading the workbook):**\n- **Number** – Excel cell format Number or General.\n- **Date** – Excel cell format Date, or Text whose value matches one of: `yyyy-mm-dd`, `yyyy/mm/dd`, `dd-mm-yyyy`, `dd/mm/yyyy`.\n- **DateTime** – Excel cell format Date, or Text whose value matches one of: `yyyy-mm-dd hh:mm:ss`, `yyyy/mm/dd hh:mm:ss`, `dd-mm-yyyy hh:mm:ss`, `dd/mm/yyyy hh:mm:ss`.\n- **Link** – `[Link text] (https://example.com/)`.\n- **User or Group** – `user:Full Name` or `group:Group Name` / `group:Group Alias`. Example: `user:Antonio García`, `group:Data Team`.\n- **User** – The user's full name without the `user:` prefix.\n- **Group** – Group name or alias without the `group:` prefix.\n- **Table / Dynamic Table** – Column headers separated by semicolons (`;`), with a line break inside the cell separating headers from data rows.\n- **Multiple Values** – Values separated by pipe (`|`). Example: `user1|user2|user3`.\n- **Rich Text** – Downloaded and uploaded without formatting; remove the column unless uploading plain text content.\n- **Dropdown / Radio / Checkbox** – Values must match the template definition exactly (case‑sensitive).\n\nLanguage falls back to the configured default if the requested language is not configured or a translation is missing.\n","operationId":"TdDdWeb.DataStructures.XLSXController.download","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureXlsxDownloadRequest"}}},"description":"Download filters","required":false},"responses":{"200":{"content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"format":"binary","type":"string"}}},"description":"XLSX file download"},"204":{"description":"No data structures available for download"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Download data structures as XLSX","tags":["XLSX"]}}},"components":{"schemas":{"DataStructureXlsxDownloadRequest":{"additionalProperties":false,"description":"Exports structure metadata as an XLSX workbook using the same format as the upload flow. The workbook contains one sheet per structure type and includes the standard fixed columns plus template fields when the exporter is configured for editable metadata. `download_type` currently supports `editable`; `note_type` accepts `published` or `non_published`; `lang` defaults to the configured app language; `header_labels` allows overriding the displayed column names.","properties":{"data_structure_id":{"description":"Filter by a specific structure ID.","nullable":true,"type":"integer"},"download_type":{"description":"Download format. `editable` exports the structure metadata in the editable worksheet format.","enum":["editable"],"nullable":true,"type":"string"},"header_labels":{"additionalProperties":{"type":"string"},"description":"Optional map of custom column labels keyed by the original field name.","nullable":true,"type":"object"},"include_children":{"default":false,"description":"When true, include child structures in the export.","nullable":true,"type":"boolean"},"lang":{"default":"en","description":"Language used for labels and translations. Defaults to the configured application language.","nullable":true,"type":"string"},"note_type":{"description":"Which note content to export. `published` exports the published note; `non_published` exports the latest non-published note.","enum":["published","non_published"],"nullable":true,"type":"string"},"page":{"description":"Page number (not used for the workbook export itself).","nullable":true,"type":"integer"},"query":{"description":"Full-text search query","nullable":true,"type":"string"},"size":{"description":"Page size (not used for the workbook export itself).","nullable":true,"type":"integer"},"structure_url_schema":{"description":"URL template used to build the `link_to_structure` column","nullable":true,"type":"string"}},"title":"DataStructureXlsxDownloadRequest","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Upload data structures from XLSX

> Uploads an Excel (XLSX) workbook to create or update structure notes. The same file can contain both new notes and updates to existing ones, in a single upload.\
> \
> \*\*Permissions:\*\*\
> Requires \*\*'Create note'\*\* or \*\*'Edit note'\*\* permission. When the upload is intended to publish content, the caller must additionally hold \*\*'Publish note'\*\*. The upload is processed as a background job, so the caller must have the appropriate note‑creation or note‑editing permission at the time of job creation; per‑structure workflow permissions (including publishing) are validated when the job runs.\
> \
> \*\*Request body (multipart/form-data):\*\*\
> \- \`structures\` (required, file) – XLSX file using the same format produced by the download endpoint (one sheet per structure type).\
> \- \`auto\_publish\` (optional, boolean) – When \`true\`, the workflow may publish the content if the caller has the required permission and the published content would change. Default: \`false\`.\
> \- \`lang\` (optional, string) – Language for labels and translations during import. Defaults to the server‑configured application language; the API does not read the browser language.\
> \
> \*\*Workbook structure:\*\* One sheet per structure type. For each row, the structure type is inferred from \`external\_id\`, which determines the corresponding template. Columns are validated against that template.\
> \
> \*\*Row semantics:\*\*\
> \- \*\*Required fields:\*\* \`external\_id\`, plus all template‑required fields when the row creates a new note.\
> \- A column that is \*\*not present\*\* in the file leaves the corresponding field unchanged.\
> \- A column that is \*\*present but empty\*\* clears the field.\
> \- New notes and updates can be mixed in the same file.\
> \
> \*\*Versioning behavior:\*\*\
> \- If a published version exists and the file is uploaded with the publish option but the content has not changed, \*\*no new version is created\*\*.\
> \- Uploading as a \*\*draft always creates a new draft version\*\*, even if the content is unchanged.\
> \
> \*\*Behavior:\*\* The workbook is parsed and the note updates are queued as a background job. The endpoint returns a \`job\_id\`, which can be used to track progress via the file bulk‑update events endpoint. Errors are reported per row through the event's \`response\` payload.\
> \
> \*\*Field formats (Excel uploads):\*\*\
> \- \*\*Number\*\* – Excel cell format Number or General.\
> \- \*\*Date\*\* – Excel cell format Date, or Text whose value matches one of: \`yyyy-mm-dd\`, \`yyyy/mm/dd\`, \`dd-mm-yyyy\`, \`dd/mm/yyyy\`.\
> \- \*\*DateTime\*\* – Excel cell format Date, or Text whose value matches one of: \`yyyy-mm-dd hh:mm:ss\`, \`yyyy/mm/dd hh:mm:ss\`, \`dd-mm-yyyy hh:mm:ss\`, \`dd/mm/yyyy hh:mm:ss\`.\
> \- \*\*Link\*\* – \`\[Link text] (<https://example.com/)\\`.\\>
> \- \*\*User or Group\*\* – \`user:Full Name\` or \`group:Group Name\` / \`group:Group Alias\`. Example: \`user:Antonio García\`, \`group:Data Team\`.\
> \- \*\*User\*\* – The user's full name without the \`user:\` prefix.\
> \- \*\*Group\*\* – Group name or alias without the \`group:\` prefix.\
> \- \*\*Table / Dynamic Table\*\* – Column headers separated by semicolons (\`;\`), with a line break inside the cell separating headers from data rows.\
> \- \*\*Multiple Values\*\* – Values separated by pipe (\`|\`). Example: \`user1|user2|user3\`.\
> \- \*\*Rich Text\*\* – Downloaded and uploaded without formatting; remove the column unless uploading plain text content.\
> \- \*\*Dropdown / Radio / Checkbox\*\* – Values must match the template definition exactly (case‑sensitive).\
> \
> \*\*Result\*\* If the workbook cannot be parsed (missing required columns, invalid structure type, unknown external\_id), the endpoint returns \`422 Unprocessable Entity\`. Individual rows that fail validation are still reported as errors in the job's event record while valid rows are applied.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/data_structures/xlsx/upload":{"post":{"description":"Uploads an Excel (XLSX) workbook to create or update structure notes. The same file can contain both new notes and updates to existing ones, in a single upload.\n\n**Permissions:**\nRequires **'Create note'** or **'Edit note'** permission. When the upload is intended to publish content, the caller must additionally hold **'Publish note'**. The upload is processed as a background job, so the caller must have the appropriate note‑creation or note‑editing permission at the time of job creation; per‑structure workflow permissions (including publishing) are validated when the job runs.\n\n**Request body (multipart/form-data):**\n- `structures` (required, file) – XLSX file using the same format produced by the download endpoint (one sheet per structure type).\n- `auto_publish` (optional, boolean) – When `true`, the workflow may publish the content if the caller has the required permission and the published content would change. Default: `false`.\n- `lang` (optional, string) – Language for labels and translations during import. Defaults to the server‑configured application language; the API does not read the browser language.\n\n**Workbook structure:** One sheet per structure type. For each row, the structure type is inferred from `external_id`, which determines the corresponding template. Columns are validated against that template.\n\n**Row semantics:**\n- **Required fields:** `external_id`, plus all template‑required fields when the row creates a new note.\n- A column that is **not present** in the file leaves the corresponding field unchanged.\n- A column that is **present but empty** clears the field.\n- New notes and updates can be mixed in the same file.\n\n**Versioning behavior:**\n- If a published version exists and the file is uploaded with the publish option but the content has not changed, **no new version is created**.\n- Uploading as a **draft always creates a new draft version**, even if the content is unchanged.\n\n**Behavior:** The workbook is parsed and the note updates are queued as a background job. The endpoint returns a `job_id`, which can be used to track progress via the file bulk‑update events endpoint. Errors are reported per row through the event's `response` payload.\n\n**Field formats (Excel uploads):**\n- **Number** – Excel cell format Number or General.\n- **Date** – Excel cell format Date, or Text whose value matches one of: `yyyy-mm-dd`, `yyyy/mm/dd`, `dd-mm-yyyy`, `dd/mm/yyyy`.\n- **DateTime** – Excel cell format Date, or Text whose value matches one of: `yyyy-mm-dd hh:mm:ss`, `yyyy/mm/dd hh:mm:ss`, `dd-mm-yyyy hh:mm:ss`, `dd/mm/yyyy hh:mm:ss`.\n- **Link** – `[Link text] (https://example.com/)`.\n- **User or Group** – `user:Full Name` or `group:Group Name` / `group:Group Alias`. Example: `user:Antonio García`, `group:Data Team`.\n- **User** – The user's full name without the `user:` prefix.\n- **Group** – Group name or alias without the `group:` prefix.\n- **Table / Dynamic Table** – Column headers separated by semicolons (`;`), with a line break inside the cell separating headers from data rows.\n- **Multiple Values** – Values separated by pipe (`|`). Example: `user1|user2|user3`.\n- **Rich Text** – Downloaded and uploaded without formatting; remove the column unless uploading plain text content.\n- **Dropdown / Radio / Checkbox** – Values must match the template definition exactly (case‑sensitive).\n\n**Result** If the workbook cannot be parsed (missing required columns, invalid structure type, unknown external_id), the endpoint returns `422 Unprocessable Entity`. Individual rows that fail validation are still reported as errors in the job's event record while valid rows are applied.\n","operationId":"TdDdWeb.DataStructures.XLSXController.upload","parameters":[],"requestBody":{"content":{"multipart/form-data":{"schema":{"additionalProperties":false,"description":"XLSX upload payload for note updates and creates. The workbook is the same format as the download: one sheet per structure type, with the template resolved from each structure `external_id`. Required fields are `external_id` and the template-required fields for creates. If a column is omitted, the value is not updated; if the column is present but empty, the field is cleared.","properties":{"auto_publish":{"default":false,"description":"If true, the workflow may publish the content when allowed. If the published content is unchanged, no new version is created.","type":"boolean"},"lang":{"default":"en","description":"Language used for labels and translations during the import. Defaults to the configured application language when omitted.","type":"string"},"structures":{"description":"XLSX file containing the structure data to import.","format":"binary","type":"string"}},"required":["structures"],"title":"DataStructureXlsxUploadRequest","type":"object"}}},"description":"XLSX upload payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataStructureXlsxUploadResponse"}}},"description":"Upload job created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Upload data structures from XLSX","tags":["XLSX"]}}},"components":{"schemas":{"DataStructureXlsxUploadResponse":{"properties":{"job_id":{"type":"integer"}},"title":"DataStructureXlsxUploadResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```