Get Started with Sigma's API

Sigma’s REST API allows developers to communicate directly with Sigma. It supports actions across a broad selection of Sigma features, including:

• Connections
• Datasets
• Files
• Grants
• Members
• Query (to downloaded the result of Workbook exports using the given 'queryId')
• Tags
• Teams
• User Attributes
• Workspaces
• Workbooks

All endpoints have resource-oriented URLs, which can be accessed over HTTPS. Endpoints accept JSON in the request body and can include JSON in their response. Responses from the Query API endpoint for files requested with the Workbook Export API can include CSV, XLSX, PDF, PNG and JSON types.

Account-based HTTPS authentication provides security for your org's information.

Where do I start?

Your starting point with Sigma’s API is dependent on your role, purpose, and prior knowledge of APIs. To get started, find the scenario below that best matches your current situation:

Scenario #1: I don’t know what an API is.

API stands for Application Programming Interface. APIs act as a middleman between two applications, allowing them to communicate various information.

APIs consist of endpoints for specific lines of communication–similar to how large companies have multiple phone lines that each serve a different purpose.

Developers on your team can run code that calls an endpoint on Sigma’s API. Sigma responds with the requested information or perform the requested action.

Scenario #2: I’m an organization admin looking to get my developers up and running with Sigma’s API.

Before a developer can get started with Sigma’s API, you will need to provide them with a Client ID and API Token. These values will allow the developer to authenticate with Sigma’s API.

We highly recommend that you create a new Client ID/API Token pair for each individual developer, as API tokens are account-based, allowing you control over any given user’s access.

Scenario #3: I’m a developer who wants to get started with Sigma’s API.

If you do not already have a Client ID and API token to authenticate with Sigma’s API, please contact an organization Admin. They can use the instructions to get you set up: Generate API client credientials

Once you have these values, you’re ready to explore Sigma’s API endpoints. We recommend using either Swagger or cURL to get started.

Identify which API URL to use according to your Sigma organization's cloud provider

The URL you use must correspond to the cloud provider your Sigma organization is hosted on. This information is listed in the Administration Portal under Account > General Settings > Site > Cloud.

For GCP organizations, use:

POST https://api.sigmacomputing.com/v2/auth/token

For AWS US organizations, use:

POST https://aws-api.sigmacomputing.com/v2/auth/token

For AWS Canada organizations, use:

POST https://api.ca.aws.sigmacomputing.com/v2/auth/token

For AWS Europe organizations, use:

POST https://api.eu.aws.sigmacomputing.com/v2/auth/token

For Azure organizations, use:

POST https://api.us.azure.sigmacomputing.com/

API Testing Grounds

Both Swagger and cURL can be used as testing grounds for Sigma’s API endpoints.

There is no limit to the number of API calls per day.

Swagger

Swagger allows you to use Sigma’s API directly from the browser.

See Sigma and Swagger or navigate to Sigma's Swagger playground.

cURL

You may prefer to use cURL to access Sigma’s API. Example cURL requests are included throughout Sigma’s API endpoint documentation.

For authentication instructions, see Authenticating with cURL.

Example Scripts

Sigma's Sample API GitHub repository contains example scripts that use Sigma's public API. Use it as a starting point for interacting with our API, to understanding common patterns and flows.

Supported endpoints

Parameter Page Limits for Paginated Responses

• Default page size: 50
• Max page size: 1000

Connections

The Connection API has the following end points:

POST /v2/connections

      Use this endpoint to create a data warehouse connection object; see Create a connection.

GET /v2/connections?limit=<number>&page=<page-string>

Returns a list of active data warehouse connection objects; see List connections.

GET /v2/connections/{connectionId}

Returns a connection object based on the input connectionId; see Look up a connection.

PUT /v2/connections/:id

      This endpoint for updating or restoring a connection object to a data warehouse; see Update a connection.

GET /v2/connections/:connectionId/test

Use this endpoint to validate a data warehouse connection object; see Test a connection.

DELETE /v2/connections/:connectionId

Use this endpoint to delete a data warehouse connection object; see Delete a connection.

Connection path

The Connection Path API has the following end point:

POST /v2/connection/{connectionId}/lookup

Returns the inodeId associated with the requested warehouse connection path.

Connection grants

The Connection Grants API has the following end points:

GET /v2/connections/{connectionId}/grants

Returns a list grants associated with the requested connection.

POST /v2/connections/{connectionId}/grants

Creates a connection grant for a team or user. Returns an empty object.

DELETE /v2/connections/{connectionId}/grants/{grantId}

Revokes an existing grant. Returns an empty object.

Workbooks

The Workbook API has the following end points:

GET /v2/workbooks

Returns a list of available workbooks

GET /v2/workbooks/{workbookId}

Returns a workbook object based on a unique workbook identifier, workbookId.

GET /v2/workbooks/{workbookId}/schema

Returns a workbook schema object based on a workbookId.

POST /v2/workbooks/{workbookId}/export

Returns a workbook export query object based on a workbookId.

Datasets

The Dataset API has the following end points:

GET /v2/datasets

Returns a list of datasets in your organization.

GET /v2/datasets/{datasetId}

Returns a dataset object based on its unique identifier, datasetId.

Dataset materialization

The Dataset Materialization API has the following end points:

GET /v2/datasets/{datasetId}/materialization

Returns a list of materializations for the dataset.

POST /v2/datasets/{datasetId}/materialization

Initiates a new materialization of the specified dataset.

Queries

The Query API has the following end point:

GET /v2/query/{queryId}/download

Downloads the result of a successful query.

Teams

The Team API has the following end points:

GET /v2/teams

Returns a list of teams in your organization.

GET /v2/teams/{teamId}

Returns a team object based on its unique identifier, teamId.

POST /v2/teams

Creates a new team, and returns a team object.

PATCH /v2/teams/{teamId}

Updates the team's metadata and returns the associated team object.

PATCH /v2/teams/{teamId}/members

Based on the entered parameters, adds or removes team members. Returns an empty object.

DELETE /v2/teams/{teamId}

Deletes a team based on the provided unique identifier, teamId. Returns an empty object.

Organization members

The Organization Member API has the following end points.

GET /v2/members

Returns a list of members in your organization.

GET /v2/members/{memberId}

Returns a member object based on its unique identifier, memberId.

POST /v2/members

Sends an invite to the potential new organization member. Returns an object containing a unique identifier (memberId) associated with the new user.

PATCH /v2/members/{memberId}

Updates a user's attributes based on its unique identifier, memberId, and the request body. Returns the associated member object.

DELETE /v2/members/{memberId}

Deactivates a user based on its unique identifier, memberId. Returns an empty object.

Workspaces

The Workspace API has the following end points:

GET /v2/workspaces

Returns a list workspaces in the organization.

GET /v2/workspaces/{workspaceId}

Returns a workspace’s metadata.

POST /v2/workspaces

Creates a new workspace. Returns a workspace object.

PATCH /v2/workspaces/{workspaceId}

Update the workspace’s metadata. Returns a workspace object.

DELETE /v2/workspaces/{workspaceId}

Deletes the workspace. Returns an empty object.

Workspace Grants

The Workspace Grants API has the following end points:

GET /v2/workspaces/{workspaceId}/grants

Returns a list grants associated with the requested workspace.

POST /v2/workspaces/{workspaceId}/grants

Creates a workspace grant for a team or user. Returns an empty object.

DELETE /v2/workspaces/{workspaceId}/grants/{grantId}

Revokes an existing grant. Returns an empty object.

Who Am I?

The WhoAmI API has the following end point:

GET /v2/whoami

Returns an object that identifies the current authenticated user’s id and organization.