Skip to navigation
Build from codeWorkbook representation example library

Example representation: Workbook with a call API action

View as Markdown

This is an example representation of a workbook, retrieved using the Get a workbook endpoint with the query parameter includeContents=true. Representations like this one can be used to create a workbook from code using the Create a workbook endpoint. Each page in this example library includes the code representation of the workbook and step-by-step instructions to create it in the Sigma UI.

Consult this example and others in the Workbook representation example library to:

  • Troubleshoot the formatting of a particular feature in code representation
  • Relate a feature from the Sigma UI to its representation in code
  • Provide context to AI tools used to create workbooks from code

This example representation cannot be used as-is. All identifying details, such as IDs, names, and URLs, have been replaced with randomized ID values or generic substitutions. The format of these contents, like the length of ID values, is preserved for demonstrative purposes. However, this representation cannot be directly used without modification to the base URL, connection details, and more. For more information, see Create and manage workbooks from code.

System and user requirements

To complete the steps in this example, you must meet the user requirements listed below for creating the workbook in the UI and creating it from code.

The ability to create this workbook in the Sigma UI requires the following:

  • You must be assigned an account type with the Create, edit, and publish workbooks and Trigger API actions permissions enabled.
  • You must have access to an API connector. See Create an API connector.

The ability to create a workbook from code requires the following:

Create the example workbook in the Sigma UI

This example shows a workbook with a button that calls an external API using a Call API action.

This uses the API connector configured in the Tutorial: Configure API credentials, connectors, and actions for the NYC Open Data API. To follow along with all selections and test the action, follow the steps in that tutorial to create a credential and connector first.

To create this workbook in the Sigma UI:

  1. Go to the Home page.

  2. Select Create new > Workbook.

    A new workbook opens.

  3. From the Add element bar, select UI > Button.

  4. In the editor panel, open the Actions tab.

  5. Select Add action.

  6. Configure the action with the following settings:

    OptionSetting
    ActionCall API
    APISelect NYC Open Data 311 with dynamic incident_address
    Map withStatic values for the incident_address parameter.

  7. For the incident_address parameter, enter 124 EAST 14 ST as a static value. This example uses a connector with that parameter; your connector might require different parameters.

  8. In the document header, select Save as.

  9. Enter a name for the workbook, such as call-api-action.

  10. Select Save.

Get a code representation of this workbook

To get a representation of this workbook, follow the steps in Get the code representation of a workbook.

The connectorId in this example is a placeholder. To create a workbook from the representation, replace it with the ID of an API connector in your organization.

The code representation of this workbook appears like the following:

workbookId: 4dad2986-ce83-4960-aa06-e9ab85a0bcc1
workbookUrlId: 9xslXTTIQrh6bpy0VAq3GZ
createdBy: uO2R8UziJdi0Y4mj4TIJZ9RnvIh4T
updatedBy: uO2R8UziJdi0Y4mj4TIJZ9RnvIh4T
createdAt: '2026-09-01T14:57:43.226Z'
updatedAt: '2026-11-03T20:01:36.687Z'
name: call-api-action
url: https://aws-api.sigmacomputing.com/org-name/workbook/9xslXTTIQrh6bpy0VAq3GZ
path: My Documents/<folder-name>
latestVersion: 6
ownerId: uO2R8UziJdi0Y4mj4TIJZ9RnvIh4T
isArchived: false
contents:
  schemaVersion: 1
  elements:
    - id: OetAfG82
      kind: button
      text: Call API
      appearance: filled
      actions:
        - id: EOMjRZA0G6
          trigger: on-click
          effects:
            - effect: call-api
              connectorId: 5f4807bc-6eca-4e3c-8490-ca26561d2417
              arguments:
                incident_address:
                  type: constant
                  value:
                    type: text
                    value: 124 EAST 14 ST
  pages:
    - id: Kd5WVwd9
      name: Page 1
  kind: workbook
  layout: |
    <?xml version="1.0" encoding="utf-8"?>
    <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="Kd5WVwd9">
      <Element elementId="OetAfG82" gridColumn="1 / 25" gridRow="1 / 7"/>
    </Page>
documentVersion: 6

Representing the call API action

...
actions:
- id: EOMjRZA0G6
  trigger: on-click
  effects:
  - effect: call-api
    connectorId: 5f4807bc-6eca-4e3c-8490-ca26561d2417
    arguments:
      incident_address:
        type: constant
        value:
          type: text
          value: 124 EAST 14 ST
...