Skip to content

docs: document custom_views endpoint #1759

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jacalata merged 1 commit into from
Apr 7, 2026
+109 −0
Merged

docs: document custom_views endpoint #1759

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions docs/api-ref.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -652,6 +652,115 @@ See [CustomViewItem class](#customviewitem-class)
<br>
<br>

#### custom_views.download

```py
custom_views.download(view_item, file)
```

Downloads the definition of a custom view as JSON to a file path or file object. The downloaded file may contain sensitive information.

**Version**

This endpoint is available with REST API version 3.21 and up.

Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a REST API reference link for custom_views.download, consistent with the other custom_views.* method docs (e.g., custom_views.delete includes a REST API: line).

Suggested change
**REST API:**
[Download Custom View](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#download_custom_view)

Copilot uses AI. Check for mistakes.
**Parameters**

| Name | Description |
| :---------- | :----------------------------------------------------------------------------------- |
| `view_item` | The `CustomViewItem` to download. |
| `file` | The file path (`str` or `Path`) or writable file object to write the definition to. |

**Returns**

Returns the file path or file object that the custom view definition was written to.

**Example**

```py
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The custom_views.download example references server without showing sign-in or setup (and without a note like "# Sign in, ..." used in nearby examples). Consider adding the missing setup or explicitly noting that sign-in/server creation is assumed.

Suggested change
```py
```py
# Sign in to Tableau Server or Tableau Cloud first and create `server`.

Copilot uses AI. Check for mistakes.
custom_view = server.custom_views.get_by_id('d79634e1-6063-4ec9-95ff-50acbf609ff5')
server.custom_views.download(custom_view, './my_custom_view.json')
```

See [CustomViewItem class](#customviewitem-class)

<br>
<br>

#### custom_views.publish

```py
custom_views.publish(view_item, file)
```

Publishes a custom view to Tableau Server from a JSON definition file previously downloaded with `custom_views.download`.

**Version**

This endpoint is available with REST API version 3.21 and up.

Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a REST API reference link for custom_views.publish, consistent with the other custom_views.* method docs in this section.

Suggested change
**REST API reference**
[Publish Custom View](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#publish_custom_view)

Copilot uses AI. Check for mistakes.
**Parameters**

| Name | Description |
| :---------- | :------------------------------------------------------------------------------------ |
| `view_item` | The `CustomViewItem` describing the custom view to publish. Must have a `name` set. |
| `file` | The file path (`str` or `Path`) or readable file object containing the definition. |

Comment on lines +704 to +708
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In custom_views.publish docs, the parameter description says view_item must have name set, but the Exceptions section implies this is only required in certain cases ("when passing a file object"). Please clarify the actual requirement so the docs are internally consistent.

Copilot uses AI. Check for mistakes.
**Exceptions**

| Error | Description |
| :--------------------------- | :---------------------------------------------------------------------- |
| `ValueError` | Raised if `file` is not a valid file path or file object. |
| `MissingRequiredFieldError` | Raised if `view_item.name` is not set when passing a file object. |

**Returns**

Returns the published `CustomViewItem`, or `None`.

**Example**

```py
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The custom_views.publish example uses TSC.CustomViewItem but does not import tableauserverclient as TSC, and it references server without setup. Add the import and either include sign-in/server initialization or a clear comment indicating those steps are assumed.

Suggested change
```py
```py
import tableauserverclient as TSC
# Assumes `server` is an already initialized and signed-in TSC.Server instance.

Copilot uses AI. Check for mistakes.
new_view = TSC.CustomViewItem(name='My Custom View')
published = server.custom_views.publish(new_view, './my_custom_view.json')
print(published.id)
```

See [CustomViewItem class](#customviewitem-class)

<br>
<br>

#### custom_views.filter

```py
custom_views.filter(**kwargs)
```

Returns a list of custom views that match the specified filters. Fields and operators are passed as keyword arguments in the form `field_name=value`.

Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

custom_views.filter is missing the **Version** section used by the other custom_views.* methods. If this is backed by a specific REST API version, document it; if it’s a client-side convenience helper, explicitly say so (and add a REST API link only if applicable).

Suggested change
**Version**
This is a client-side convenience helper provided by TSC. It is not a direct Tableau REST API method. For related REST API functionality, see the [Custom Views methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#custom_views).

Copilot uses AI. Check for mistakes.
**Supported fields and operators**

Field | Operators
:--- | :---
`owner_id` | `eq`
`view_id` | `eq`
`workbook_id` | `eq`

**Returns**

Returns a `QuerySet` of `CustomViewItem` objects.

**Example**

```py
my_views = server.custom_views.filter(owner_id=user_item.id)
for view in my_views:
print(view.name)
```

<br>
<br>

---

## Data Sources
Expand Down