Get started with the Sigma REST API

The Sigma REST API lets you programmatically administer and interact with the powerful analytics in Sigma.

Using the available API endpoints, you can programmatically do any the following and more:

  • Perform onboarding and offboarding of users.
  • Manage account types for users and permissions for workbooks.
  • Export data from specific workbooks.
  • Materialize data elements in a workbook.
  • Identify input tables in use in your organization.
  • Create and manage user attributes for row-level-security.

For assistance with the API, contact Sigma Support.

About the API

The Sigma API is built around REST principles, leveraging the OpenAPI specification. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. It uses built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

It supports cross-origin resource sharing, allowing you to interact securely with the API from a client-side web application, although you should never expose your secret API key in any public website’s client-side code.

Endpoints accept JSON in the request body and can include JSON in the response body.

Responses from the Query API endpoint for files requested with the Workbook Export API can include CSV, XLSX, PDF, PNG, and JSON formats as the response body.

Use of the API is governed by the Main Service Agreement.

Prerequisites

Identify your API request URL

The URL you use to send API requests depends on the cloud your Sigma organization is hosted on.

You can locate your cloud provider in the Administration section of Sigma. Go to Account > General Settings and review the Site section for the Cloud.

After you know your hosting provider, determine the Base URL to use when authenticating to the API by referring to the following table:

ProviderBase URLToken URL
AWS UShttps://aws-api.sigmacomputing.com/v2/auth/token
AWS Canadahttps://api.ca.aws.sigmacomputing.com/v2/auth/token
AWS Europehttps://api.eu.aws.sigmacomputing.com/v2/auth/token
AWS UKhttps://api.uk.aws.sigmacomputing.com/v2/auth/token
Azure UShttps://api.us.azure.sigmacomputing.com/v2/auth/token
GCPhttps://api.sigmacomputing.com/v2/auth/token

Make API calls

After you complete the prerequisites, you can start making API calls. You can use any of the following:

  • cURL from the command line.
  • Postman or another API client.
  • Write a script using your preferred language.
  • The web interface of the REST API documentation to make test API calls.

The reference pages for each API endpoint include code samples for a wide variety of languages, such as Node.js, Ruby, Python, and more.

To download the API definition for use with Postman or another API client, click the following button:

You can follow the Sigma API with Postman QuickStart for more guidance.

Example scripts and recipes

For code examples and scripts for common use cases, you can refer to the following:

You can use these scripts and code samples as a starting point for programmatically interacting with the API and for help understanding common patterns and flows.

API limits

The v2/auth/token endpoint is rate limited to 1 request per second.

The Sigma API does not enforce a limit on the number of API requests you can send per day.

There is a limit of paginated responses from API endpoints that support pagination:

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

API errors

If you receive a 401 unauthorized error response from the API, your API token might be expired:

{
    "requestId": "2da86966-9666-48e6-b100-ea47a8d9fdbe",
    "message": "We cannot verify your identity. Please try again later.",
    "code": "unauthorized"
}

Your API token expires after 1 hour. To refresh your token or get a new one, see Get access token.