Skip to main content

Update Custom Report

PUT 
/api/v2/custom-reports/:customReport

Update a saved report. The owner, or a user it was shared with edit permission, can update it (403 otherwise). Only the owner can change visibility — it is ignored when an edit-share recipient sends it.

Required scope: reports:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

All fields are optional: name (max 255), description (max 1000), base_entity (max 100), definition, visibility (private or shared) and change_note (string). When definition is sent, definition.base_entity and definition.columns are required and follow the same rules as Create Custom Report. Changing the definition first saves the previous one as a version (with your change_note), which you can see with List Report Versions and roll back with Restore Report Version.

SQL reports: send definition as {"version": 2, "mode": "sql", "sql": "SELECT ...", "limit": 500} instead of a builder definition (sql max 20000 characters, limit 1-5000, display.view_type may only be table); base_entity is not needed (the report is stored under the sql domain with mode = sql). The statement is validated before it is saved (errors are returned as 422 on definition.sql). Creating or changing an SQL report requires the reports.sql permission (403 otherwise). This also applies to edit-share recipients: without the permission they can rename an SQL report but not change its statement.

Returns 404 if the report is not found or not visible to you.

Authentication: Bearer token (Personal Access Token). Personal access tokens need the reports:write scope.

Request​

Responses​

OK

Response Headers
    Content-Type