> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.sigmacomputing.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server. # Convert a workbook to a report POST https://api.sigmacomputing.com/v2/workbooks/{workbookId}/convertToReport Content-Type: application/json This endpoint converts an existing workbook into a new report. When you convert a workbook, the existing workbook is not modified. Elements and functionality in the workbook that are not supported in reports are listed in a `warnings` array in the response. Unsupported workbook contents are either removed (not added to the new report) or, if supported contents depend on them, are added to a hidden page at the end of the report. See [Limitations and unsupported elements](https://help.sigmacomputing.com/docs/convert-workbooks-to-reports#limitations-and-unsupported-elements). You can also convert a workbook to a report from the UI. See [Convert workbooks to reports](https://help.sigmacomputing.com/docs/convert-workbooks-to-reports). ### Usage notes - Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint. - The **name** parameter is required. - Use **destinationFolderId** to choose where to save the report. If not provided, the report is saved to your **My Documents** folder. - Use **pageIds** to convert only specific workbook pages. If not provided, the entire workbook is converted. - Use **format** to set the page size and orientation. The default size is letter, and the default orientation is portrait. Reference: https://help.sigmacomputing.com/reference/convert-workbook-to-report ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: sigma-rest-api version: 1.0.0 paths: /v2/workbooks/{workbookId}/convertToReport: post: operationId: convertWorkbookToReport summary: Convert a workbook to a report description: >- This endpoint converts an existing workbook into a new report. When you convert a workbook, the existing workbook is not modified. Elements and functionality in the workbook that are not supported in reports are listed in a `warnings` array in the response. Unsupported workbook contents are either removed (not added to the new report) or, if supported contents depend on them, are added to a hidden page at the end of the report. See [Limitations and unsupported elements](https://help.sigmacomputing.com/docs/convert-workbooks-to-reports#limitations-and-unsupported-elements). You can also convert a workbook to a report from the UI. See [Convert workbooks to reports](https://help.sigmacomputing.com/docs/convert-workbooks-to-reports). ### Usage notes - Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint. - The **name** parameter is required. - Use **destinationFolderId** to choose where to save the report. If not provided, the report is saved to your **My Documents** folder. - Use **pageIds** to convert only specific workbook pages. If not provided, the entire workbook is converted. - Use **format** to set the page size and orientation. The default size is letter, and the default orientation is portrait. tags: - Workbooks parameters: - name: workbookId in: path required: true schema: type: string - name: Authorization in: header description: OAuth authentication required: true schema: type: string responses: '201': description: The response body. content: application/json: schema: $ref: >- #/components/schemas/workbooks_convertWorkbookToReport_Response_201 requestBody: description: The request body. content: application/json: schema: type: object properties: name: type: string description: Name for the new report. destinationFolderId: type: string description: >- ID of the folder in which to create the new report. Defaults to your "My Documents" folder. description: type: string description: A description for the new report. pageIds: type: array items: type: string description: >- IDs of the workbook pages to convert. Defaults to the entire workbook. format: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat description: >- Page size and orientation for the report. Defaults to letter portrait. required: - name servers: - url: https://api.sigmacomputing.com description: Server for GCP (US) hosted organizations - url: https://api.sa.gcp.sigmacomputing.com description: Server for GCP (KSA) hosted organizations - url: https://aws-api.sigmacomputing.com description: Server for AWS US (West) hosted organizations - url: https://api.us-a.aws.sigmacomputing.com description: Server for AWS US (East) hosted organizations - url: https://api.ca.aws.sigmacomputing.com description: Server for AWS Canada hosted organizations - url: https://api.eu.aws.sigmacomputing.com description: Server for AWS Europe hosted organizations - url: https://api.au.aws.sigmacomputing.com description: Server for AWS Australia and APAC hosted organizations - url: https://api.uk.aws.sigmacomputing.com description: Server for AWS UK hosted organizations - url: https://api.us.azure.sigmacomputing.com description: Server for Azure US hosted organizations - url: https://api.eu.azure.sigmacomputing.com description: Server for Azure Europe hosted organizations - url: https://api.ca.azure.sigmacomputing.com description: Server for Azure Canada hosted organizations - url: https://api.uk.azure.sigmacomputing.com description: Server for Azure United Kingdom hosted organizations - url: https://api.au.azure.sigmacomputing.com description: Server for Azure Australia hosted organizations components: schemas: V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf0PageSize: type: string enum: - letter - a4 - legal - a3 description: A standard page-size preset. title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf0PageSize V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf0Layout: type: string enum: - portrait - landscape description: Page orientation. Defaults to `portrait`. title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf0Layout V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat0: type: object properties: pageSize: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf0PageSize description: A standard page-size preset. layout: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf0Layout description: Page orientation. Defaults to `portrait`. required: - pageSize description: A standard page-size preset (letter, a4, legal, or a3). title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat0 V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf1PageSize: type: string enum: - custom description: Use a custom page size. title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf1PageSize V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf1Unit: type: string enum: - pixels - inches - centimeters description: Unit for the `width` and `height` values. title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf1Unit V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat1: type: object properties: pageSize: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf1PageSize description: Use a custom page size. unit: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormatOneOf1Unit description: Unit for the `width` and `height` values. width: type: number format: double description: Page width, in the given unit. height: type: number format: double description: Page height, in the given unit. required: - pageSize - unit - width - height description: A custom page size, in pixels, inches, or centimeters. title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat1 V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat: oneOf: - $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat0 - $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat1 description: Page size and orientation for the report. Defaults to letter portrait. title: >- V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReportTagsItems: type: object properties: versionTagId: type: string description: Unique identifier of the tag. tagName: type: string sourceVersion: type: number format: double taggedAt: type: string format: date-time taggedReportId: type: string description: Unique identifier of the tagged report. required: - versionTagId - tagName - sourceVersion - taggedAt - taggedReportId title: >- V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReportTagsItems V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReport: type: object properties: reportId: type: string description: Unique identifier of the report. reportUrlId: type: string name: type: string url: type: string path: type: string latestVersion: type: number format: double ownerId: type: string createdBy: type: string description: The identifier of the user who created this object. updatedBy: type: string description: The identifier of the user or process that last updated this object. createdAt: type: string format: date-time description: When the object was created. updatedAt: type: string format: date-time description: When the object was last updated. isArchived: type: boolean tags: type: array items: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReportTagsItems description: type: string required: - reportId - reportUrlId - name - url - path - latestVersion - ownerId - createdBy - updatedBy - createdAt - updatedAt title: >- V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReport V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaSourceWorkbook: type: object properties: workbookId: type: string description: Unique identifier of the source workbook. name: type: string description: Name of the source workbook. url: type: string description: URL of the source workbook. required: - workbookId - name - url title: >- V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaSourceWorkbook V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItemsParent: type: object properties: type: type: string description: >- Unsupported parent type, in kebab-case (e.g. `sidebar-panel`, `repeater`, `modal`). id: type: string description: ID of the unsupported parent in the source workbook. required: - type - id description: The unsupported parent that caused this element to drop, if applicable. title: >- V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItemsParent V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItems: type: object properties: type: type: string description: Element type, in kebab-case. count: type: number format: double description: Number of affected elements of this type. sourceElementIds: type: array items: type: string description: IDs of the affected elements in the source workbook. reportElementIds: type: array items: type: string description: IDs of the affected elements in the new report. parent: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItemsParent description: >- The unsupported parent that caused this element to drop, if applicable. required: - type - count title: >- V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItems V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItems: type: object properties: code: type: string description: >- Machine-readable warning code, in kebab-case. Treat this as an open set and handle unknown codes gracefully. message: type: string description: Human-readable explanation of the warning. details: type: array items: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItems description: Per-element details for this warning, when available. required: - code - message title: >- V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItems workbooks_convertWorkbookToReport_Response_201: type: object properties: convertedReport: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReport sourceWorkbook: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaSourceWorkbook warnings: type: array items: $ref: >- #/components/schemas/V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItems description: >- Warnings about content that could not be carried over to the report. May be empty. required: - convertedReport - sourceWorkbook - warnings title: workbooks_convertWorkbookToReport_Response_201 securitySchemes: OAuth: type: http scheme: bearer description: OAuth 2.0 authentication ``` ## Examples **Request** ```json { "name": "string" } ``` **Response** ```json { "convertedReport": { "reportId": "string", "reportUrlId": "string", "name": "string", "url": "string", "path": "string", "latestVersion": 1.1, "ownerId": "string", "createdBy": "string", "updatedBy": "string", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "isArchived": true, "tags": [ { "versionTagId": "string", "tagName": "string", "sourceVersion": 1.1, "taggedAt": "2024-01-15T09:30:00Z", "taggedReportId": "string" } ], "description": "string" }, "sourceWorkbook": { "workbookId": "string", "name": "string", "url": "string" }, "warnings": [ { "code": "string", "message": "string", "details": [ { "type": "string", "count": 1.1, "sourceElementIds": [ "string" ], "reportElementIds": [ "string" ], "parent": { "type": "string", "id": "string" } } ] } ] } ``` **SDK Code** ```python import requests url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport" payload = { "name": "string" } headers = { "Authorization": ".", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport'; const options = { method: 'POST', headers: {Authorization: '.', 'Content-Type': 'application/json'}, body: '{"name":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport" payload := strings.NewReader("{\n \"name\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", ".") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = '.' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport") .header("Authorization", ".") .header("Content-Type", "application/json") .body("{\n \"name\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport', [ 'body' => '{ "name": "string" }', 'headers' => [ 'Authorization' => '.', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "."); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": ".", "Content-Type": "application/json" ] let parameters = ["name": "string"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/convertToReport")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```